Combining Jekyll, Haml and Sass with GitHub Pages
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.
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
content. Therefor I decided to call Rake to the rescue and use
the following rule to generate the HTML for the
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.
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
To be able to fill the
<meta keywords... each post puts keywords
appropriate for the post in the Yaml Front Matter.
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.