Moving to Jekyll

Warning: This blogpost has been posted over two years ago. That is a long time in development-world! The story here may not be relevant, complete or secure. Code might not be complete or obsoleted, and even my current vision might have (completely) changed on the subject. So please do read further, but use it with caution.
Posted on 11 Dec 2015
Tagged with: [ Wordpress ]  [ Jekyll

As you might notice, i’ve switched my blogging engine from Wordpress to Jekyll. There are actually a few reasons for this:

  • Writing blogposts in markdown is much easier than using the editor in WordPress.
  • I don’t need to update my WordPress / plugins every single day.
  • I don’t need to run a ton of plugins in order to do something useful, and worry about plugins not working after updates (like comments).
  • It’s much easier to tweak Jekyll than WordPress.

So why Jekyll, which is based/written in Ruby? Surely a PHP developer should use something like sculpin? Well, I could have, and I actually tried it already. But I didn’t really like it. Also, Jekyll provided more documentation and a larger user base. Plus the fact that another site I’m hosting called,, also uses Jekyll.

Tweaking the site

Unfortunately, moving up wasn’t a real easy process as other blog posts sometimes suggests. After finding a theme I was ok with, I had to get rid of everything I didn’t need and want, which took some time learning and knowing the theme itself. Then, I had to make sure that all information found on the old site, was mapped exactly as the new site. This is fairly easy in Jekyll, through the help of permalinks and the way blog posts have a very flexible url structure that can be changed. This is the most important aspect, as some of the blogposts are visited frequently since they are linked from some big sites (yay!, I guess).

Since the site is static, searching would be troublesome. The theme provided with a google search, so I decided to use that one. Actually, i’ve moved up to a google custom search widget, which keeps your searches inline. Unfortunately, it doesn’t work with most adblockers.

I’ve also did (a lot of) tweaking on the page layouts and added random headers on some pages (which isn’t easy, considering we have static sites, but a little bit of javascript magic makes it happen).

Blog posts can also be found through tags, through dates and withing a large (paginated) list of posts. Again: Jekyll makes it very easy to create these kind of pages.

Another thing that i’ve done is moving the comments to disqus, because it just makes more sense (and because: static).

Additional plugins

One of the coolest things is that it’s so easy to write a new plugin, or use existing plugins. Most of them are just a few lines of ruby code, and I’m using three of them, homebrewed and/or copied.

  • replace_regex Needed to convert special chars in tag names. This way a tag like foo/bar will actually be converted too foobar, so it will be easier to use them in url’s and to search them.
  • gravatar_filter A simple filter that takes an email address and converts it to a gravatar URL. Used for displaying an images of the author of a post.
  • category_plugin This is a plugin that will create pages for each category with all posts in that category. Since I don’t really use categories, but rather tags, I’ve changed this to use tags (tag_plugin would be a better name). So every tag I’m using, will generate a /archive/tags/<tagname> link with all the posts under this tag.

Import / Export

The biggest problem I had was actually trying to import all the blogposts from my wordpress site into Jekyll. There are some plugins for that, which I tried but seem to fail. Some manual intervention was needed, but I finally got all the blogposts nicely stored in markdown format.

Except every single one of those posts looked like crap. In part I blame myself, for writing such crap, but it turns out that many things are not converted properly. This was mostly because of the way the blogposts were setup. I ended up with <code> tags within <code> tags, and <strong> tags around each and every letter.

Since the blog consisted of almost 150 posts, I tried to automate my way through it. Removing all the unneeded <tag></tag> codes, converting <code> and <pre> classes where needed into {% highlight %} to make it work with the pygment highlighter, wordwrapped the blogposts, made sure all <ul><li> were converted properly etc.

Also, not every post used the <!--more--> tag, so I had to fix some posts up too.

Fortunately, most of the links and images were converted properly, so I did not need to worry about that too much.

At this point, I still need to go over many blogposts to make sure they look ok, and that is still a lot of work, but we’re getting there.


Well, generating a new site takes a long time. That is ok when you just add an occasional blogpost here and there, but it matters when actually creating the site. It takes about 22 seconds to generate the site, with just the blog posts. When enabling the ‘tag plugin’, it takes even longer.

It’s not a process I’d like to repeat often. I’m glad it’s done: the format and the layout I’m now using, allows me to actually convert it to anything I want. Even hosting the blog on GitHub would be no problem. Another upside, I could easily add new functionality (like a warning-message on old blogpost, or certain additional texts on certain categories/tags for some book promotion and stuff). Jekyll makes this very easy. Hopefully you’ll enjoy it too, and find the whole new layout much more readable too.