I wrote that I spent some time recently to convert my Wordpress-based weblog to Jekyll. As partially mentioned in that post, Jekyll is a “blog-aware” static content generator written in Ruby that uses a lot of existing components, like Maruku for Markdown formatting and Liquid for templating.

The documentation for each of these components is at times a bit sparse and strangely arranged. The following pages I just found but I should have read them earlier:

• Overview of Jekyll
• Bloging like a Hacker
• Jekyll

Between those three, they do a good job of discussing what Jekyll is and where it succeeds and fails. I’ll just comment on my process.

Looking over and stealing the structure of existing sites, including mine is recommended. Of course, be sure to respect the original author’s copyright for content and code (mine is Creative Commons and BSD, respectively). I borrowed Tate Johnson’s, who recently redesigned his site to explicitly mimic Latex output with CSS3 and HTML5.

The conversion process was both easy and painful: it was easy to get started and get all of the information in place, but was painful to import all 220 existing posts. Exporting the posts were painless: the provided Wordpress migration tool worked like a charm. I did have to tweak it a bit to get topic name → file name conversion just right, and to pull down the few drafts of unfinished content in the database.

Converting the posts to valid Markdown pages would have been a Herculean task, but I decided that I at least wanted to convert them to a format that Maruku would parse and export to valid HTML. Maruku is particular about where raw HTML can appear, namely approximately in its own block. A lot of time was spent wrapping things in <span>s to get Maruku to stop complaining. I wrote some shell aliases to help me with the edit-debug-commit cycle. For a large portion of the attention-required posts, I just converted to valid Markdown.

Wordpress has a nice feature that I started using liberally: if a media URL appears in the body of a post and is not contained in a tag, it uses the oEmbed standard to convert the media to an HTML representation. This meant that I had to revise all of my YouTube and Flickr references to be valid HTML or Markdown. I was half way done writing a Jekyll plugin that would support oEmbed, but then decided this defeats the purpose of having a simple, static conversion process.

The rest of the stuff was easy. I wrote an RSS 2.0 feed and heavily modified someone’s existing Atom one (both of which you should steal from me). I used Yahoo’s YUI 2 Reset-Base-Font and Grids CSS as I hate dealing with browser-specific CSS differences. I used W3C’s validator constantly. I wrote a Perl-based unit test to make it easy and integrated in my Rakefile.

I’ve so far decided against having comments, but I do have a trivial topic branch that integrates Disqus comments. I’ll probably merge it some day soon.

My next rainy day task will be categorizing or tagging posts, which Jekyll supports strangely, so a million different people have reimplemented it in different ways.

This work was worth it to uncomplicate managing this simple weblog. I can compose in Vim, write in a decent markup language, have Makefile-like automation for testing and deployment, maintain revision history and have sane branching with Git, and not have to deal with security upgrades and unnecessary slowness.