Using Jekyll

Please accept my apologies if I’ve flooded your feed reader with articles: I owe you a beer. The reason for this is I’ve moved my blog over to a new system and new design. To make up for it I’ve lovingly curated all of my old posts by adding syntax highlighting, resizing images and fixing typos.

In fact, I’ve almost killed myself porting this blog over to Jekyll. My old blog was a simple Rails application I built based on code from Helipad. It did a sterling job, but I have so many Rails applications to maintain it added too much to my workload. Writing a blog with Jekyll is relatively simple, but deciding to make a redesign at the same time is not.

Here’s why I like Jekyll, and why you might too:

• Jekyll generates static pages in a very logical way that’s easy to understand
• Anywhere that serves HTML files can serve your blog
• If you’re familiar with rake or git deployment is a breeze
• Jekyll provides some excellent syntax highlighting through pygments

Design

I wanted to include more details about my projects on the homepage, but I couldn’t figure out a design that balanced a mini portfolio with recent posts. I was really inspired by Bruce Williams' and Tom Preston-Werner' blogs for the format. Their blogs are like mine but 100% more awesome.

Jekyll Basics

Here’s an example of a Jekyll blog’s source code: bruce.github.com. Notice the directories with underscores:

_layouts/
_posts/

By default layouts are in Liquid templates.

Articles are a little more complicated, but still very intuitive:

• File names should be year–month–day/file–name.format
• The format can be textile or markdown
• Post files should include a header that indicates the layout

The headers are yaml and look like this:

---
layout: post
title: "Rapid Rails: Boot Up Time"
categories: 
- rails
- rapidrails
- ruby
- performance
---

Kool–Aid Factor

Jekyll definitely has a Kool–Aid factor because of the GitHub pages integration. People are hosting their blogs on GitHub, which makes publishing an article little more than git push.

Workflow

Working with Jekyll is like this:

1. Start jekyll --server --auto
2. Create a new file in _posts with the name year-month-day/file-name.format
3. Add the yaml header
4. Write the post
5. View http://localhost:4000 in a browser
6. Realise your design is broken in IE

Working on Designs

Jekyll needs to update the _site/ directory every time a file is changed. This can make working on designs slow, so sometimes it's good to edit files in there then copy them back. This may be considered bad practice though, so it might be more suitable to make a mock up design page with relative CSS/image links until you're happy with your design.

Tags

I tagged all my previous posts and I didn’t really want to lose them. I’ve preserved them by adding arrays of categories (see the yaml example above). Then I include them in a post with loop in liquid: for category in page.categories.

Next I generated a tags.html file that contains all of the posts for each tag. I wrote a task for this in my Rakefile, you can get the source here: generate_tags.rb.