When I first started this blog in 2006 I built it using WordPress. It's a good, solid platform with a whole bunch of useful extensions, and it's not too difficult to get it set up quickly.

The last year or so though I started adding more to the front of the site, such as resources, guides and the personal development blog list. It wouldn't have been too difficult to build these in WordPress, but it wasn't something I was particularly interested in doing. Most of my freelance work involves WordPress, so perhaps after working with it all day that's why I wasn't too excited by it.

In the end I decided to try out Jekyll. It took a bit of getting used to, but it quickly grew on me. Not only is the site much, much faster now, but I find it easier to add new stuff without worrying about creating custom plugins or templates.

Site Speed - Before and After
Figure 1: See if you can guess when the site switched to Jekyll…

Although the speed of static pages is a huge plus, for me Jekyll's strongest feature is the custom post meta. Each file has a short YAML header, and any extra data can then be accessed in templates. This made it much easier to build the resources section, and as it's plaintext it doesn't take long to add new data.

Rebuilding the site

Of course, it wouldn't be me if I didn't try and do something far more complex than necessary. The standard Jekyll layout is pretty bare-bones, and I didn't really like how pages and posts were organized. I also wanted to be able to write my posts in org-mode, which meant I needed an extra build step to do all the conversion.

My current layout looks like this:

  • _staging - This is where site files are copied to before being processed by org and built by Jekyll. Also contains a cache directory to speed up rebuilds.
  • assets - Images, styles and Javascript goes here.
  • config - Contains jekyll, emacs and other configs required to build the site
  • content - All site content lives here.
    • comments
    • pages
    • posts
  • data - Data used when generating things goes here. Mostly the bits database.
  • plugins - Jekyll & Phing plugins live here
  • scripts - Bits generation scripts live here, along with other bits of code for generating the blog list.
  • templates - Any templates live here
    • bits
    • layouts
    • partials

I use phing to manage the build process, which goes something like this:

  • Copy assets, content and templates to the _staging directory
  • Use emacs to convert org-files to html
  • Copy files to the correct place (such as moving content/posts to _posts) and rename them for nicer permalinks
  • Build stylesheet using sass
  • Build using jekyll
  • Run some cleanup filters & insert analytics code

This all goes into _staging/_to_deploy, which is then deployed to the live site using rsync. There's certainly room for improvement, but so far it's been extremely quick.


Like WordPress, Jekyll can be extended using plugins. Jekyll plugins can be used to generate additional pages from data (such as archives), or add new filters & tags to template system.

I used the following plugins (some with a little modification):

  • ancestors.rb - This adds support for accessing a page or post's ancestors. It's used to generate the breadcrumbs at the top.
  • archive_page.rb - A plugin I wrote to generate the archives page. The appearance is base on the "smart archives" plugin for WordPress.
  • category_generator.rb - Generates category pages. They're not quite as nice as WordPress's (no pagination), but they get the job done. After viewing my site stats it didn't seem worth adding "proper" category archives as virtually nobody uses them.
  • sitemap_generator.rb - Creates the sitemap used by the site.
  • static_comments.rb - Adds support for comments. Comments work in pretty much the same way as posts. Each post has a directory for comments, and each comment lives in its own file.


There were a couple of problems I ran into during the conversion:

  • I changed the permalink structure from "/blog/year/month/slug/" to just "/blog/slug/", which meant any links to old posts would no longer work.
  • Jekyll doesn't generate category or date archive pages by default, and the pages that are generated don't support pagination. Not a huge problem, but some of the most popular pages on the site were pages in the date archives.

Thankfully both of these were solvable with a little bit of nginx code:

Redirect permalinks

# Redirects old date-based slugs to just plain article
location ~ "^/blog/(\d{4})/(\d{2})/(.*)/?$" {
    return 301 /blog/$3;

Redirect date archives

# Redirect year archives to archives page
location ~ "^/blog/(\d{4})/?$" {
    return 301 /blog/archives/#archive-$1;

# Redirect month archives to archives page
location ~ "^/blog/(\d{4})/(\d{2})/?$" {
    return 301 /blog/archives/#archive-$1-$2;

The result

It's more complicated than it needs to be, but overall I'm pretty please with how the move went.

Originally site generation was quite slow (2-3 minutes), so now I cache all generated content so it only needs rebuilding if something changes. That took the build time to around 15 seconds, which is plenty quick enough for my needs.

The only issue I've had so far is the site has pretty much dropped off Google. It didn't get a huge amount of traffic before, but Google Webmaster shows it has gone from about daily search 1,000 impressions to under 50. I'm pretty sure it's due to the change in permalink structure, but I'm hoping things will get better in time.