Hakyll setup
Here is the first post on the CBMM @ Github website. As explained on the About page, we wanted a space to organize the open-source activity going on at the CBMM, beyond just the wall of repositories on our github org page.
The design decisions reflect the broader universe of the CBMM software situation. The developer staff is small, and there are far more projects to do than people to do them. At the same time we want the site to be reliable to maintain and simple to edit with the same workflow that we use for developing software. We also want the development process to be totally open. So, GitHub pages is an extremely good fit for hosting. We don’t have to do any maintenance or worry at all about backups. And the site content is generated mainly from markdown via the fantastic document converter pandoc and static site generator Hakyll.
We will be exercising Pandoc and Hakyll more in the future, especially looking at whether they are a good fit for publication-like posts with references and figures. But for now, getting basic blog functionality, quick uploads, and very small page sizes, I’m happy with the tech choices.
The rest of this post consists notes on design goals and things that needed tweaking for all the parts to fit together. If they help inform you in your own site set-up, then I’m happy.
Load time
Fast page loads are important1, and high-res monitors are becoming more popular, so the big banner at the top is an SVG image drawn in inkscape and weighing in at a delicate 24.1 kB (right-click, the choose select from the context menu, find the Network tab, and reload the page to get a listing of the assets and their sizes). I went with Yahoo’s Pure CSS for a change, instead of the more typical Twitter Bootstrap. Together Pure’s files are less than 6 kB (compared to bootstap, which is closer to 30 kB). These are all very small numbers. But it was fun to get to try something different. Getting the responsive display hamburger menu working required copying some HTML from the side-menu Pure layout example.
Sticky Footer2
The recommended trick of using a flexbox to achieve a sticky footer3 didn’t work for me, probably because the responsive nav element has a strange shape that confuses the flexbox layout (or possibly just the person trying to use the flexbox layout).
The workaround was to wrap all of the body content together in a <div class="layout"> and make that layout div the display: flex container, rather that assigning that role directly to the <body>.
Hamburger space
I prefer when the a sliding side menu covers the underlying content, rather than pushing the content over to make space. The latter is the default in PureCSS’s side-menu layout. Changing that was a matter of dropping the left: 150px in the #layout.active property of side-menu.css.
Active link
Although PureCSS offers some javascript to highlight the menu item corresponding to the page you’re looking at, I wanted to try to handle this statically in Hakyll, and I followed Mesokurtosis’s blog instructions to a T. Frankly I don’t have any intuition about how Hakyll’s templating system or compilers work (I should get on that!). Fortunately, one can clearly put a site together without understanding very much.
Teasers, RSS, and Tags
Here again, I have some homework to do to understand the Hakyll compilation process. I followed verbatim the instructions from Hakyll’s author, Jasper Van der Jeugt, and another more hand-holding guide.
To set up the RSS feed I followed another of Jasper’s tutorials. And for post tags, I looked at his own blog’s repository and another guide. I’d be lying if I didn’t admit some shame for taking so many shortcuts! But please do have a look at the repository and feel free to clone the whole thing if this is a reasonably starting-point for your own Hakyll blog.
Deployment
To manage the interaction with GitHub Pages, I keep all of the site’s sources on the hakyll branch. When Hakyll compiles a site, it puts the whole thing into a directory called _site in the root of the project. By adding this repository’s master branch as a submodule under the name _site, I’m able to deploy the site by simply cding into _site, committing all the files and pushing them to the master branch. This method I learned from a Stack Builders blog post. The script to do the pushing is here.
Sometimes it’s the easiest-seeming things that are hardest in programming and web design. ‘Sticky footer’ refers to the ability for the page’s footer to stick to the very bottom of the window, even if the window’s other content is short and doesn’t reach the bottom. It can be surprisingly hard to make this happen reliably. See the flexbox solution for a clearer demo of what I mean here. Relatedly, this pattern is called the “Holy Grail” layout, because it’s often what the designer has in mind while being surprisingly tricky to implement.↩
https://philipwalton.github.io/solved-by-flexbox/demos/sticky-footer/↩
