Combining Jekyll, Haml and Sass with GitHub Pages

Using Git introduced me to the wonderful services of GitHub. One of the many great features of GitHub is something known as GitHub Pages. To quote the GitHub Pages intro:

The GitHub Pages feature allows you to publish content to the web by simply pushing content to one of your GitHub hosted repositories. You can use GitHub Pages for the website of your project or as a ‘User Page’. GitHub uses Git’s post-commit hooks, to invoke Jekyll a Ruby based static site generator.

Enter Haml

Writing HTML by hand is somewhat tiresome, Jekyll relieves this burden for the most part by providing rendering of Markdown or Textilize if that’s what you prefer. The layout pages still require you to write HTML though. Haml is a Rails view engine that has a really nice syntax and has the ability to execute Ruby code. After converting my default layout from HTML to Haml, I was really happy with the result. The structure was much more clear and no more of those missing end tags. Haml is not integrated into the stock Jekyll version, here is a Jekyll plugin, that does the trick. This plugin works great for the content and stylesheets but does not work for the _layout content. Therefor I decided to call Rake to the rescue and use the following rule to generate the HTML for the _layout directory

Note the non-standard output filename on line 2, this is needed because Jekyll does not use extensions when referring to layouts and it chooses any file in the _layout directory with the correct base name. With this rule in place I can generate my layout using Haml. Since I was rendering the layout HTML locally I decided to skip the plugin altogether and generate the CSS with Sass locallly as well. Since this also gives me more control and I can be sure that the page rendered locally will look exactly the same once everything is committed. For generating the CSS I use the following rule:

Generating a tag cloud

Using Haml in the layout page opens some interesting possibilities since we can embed Ruby code inside the template. I found some Rake snippets to generate tag lists using Jekyll’s api. Adapt that code a bit and Haml can generate the tag cloud using Jekyll. This in turn gets used as part of the layout for each post. Isn’t that a wonderful self referential system. Here’s the Haml code to produce the tag list you see in the right column.

Apparently site.read_posts outputs to stdout to avoid it from clogging up the page it’s output gets rendered as an HTML comment (line 6 and 10).

Generating pages for posts per tag

Also inspired by this gist I added a Rake task to generate a page for each used tag in the site containing all posts that refer to the tag. Here’s the code:

To be able to fill the <meta keywords... each post puts keywords appropriate for the post in the Yaml Front Matter. The function aggregate_keywords just puts the category at hand and all the keywords from all posts in one set and returns them as a comma separated list, like so:

Next up from my blog setup backlog is a comments facility. If you’d like to use any of the code quoted above fork me on GitHub.

Sun 16 Jan 2011