Migrated to Jekyll

Oct 25, 2013 | 5 minutes read

For quite some time I’ve wanted to move my blog off WordPress and start to use Jekyll - in fact, I started looking into Jekyll back when I was still at Microsoft and had many conversations with Steve Marx about making the move. In this short post I want to discuss my motivations for making the switch and also highlight some of the unique things I did to make this quick and simple. I do not plan to get into the details of Jekyll and how it works - there are a lot of posts and articles available for you to review.

Why Did You Move to Jekyll?

I’ve already had a number of people ask my why I made the move.

  • I want more control of my HTML. I found it extremely difficult to customize and control the rendering of content with WordPress.

  • It’s just HTML. No databases. No server-side rendering of content. It’s simple.

  • Because it’s just HTML and so simple, you can host it almost anywhere. I’ve chosen Github Pages (for now), but you could easily host it on Site44, Heroku, or even Amazon S3.

  • Cost. I know there are cheaper ways to host WordPress, but I had been on GoDaddy for quite a long time. Moving to Jekyll and Github Pages removes the cost of hosting.

  • Easy to have your entire blog - most importantly all your posts! - in source control. I simply commit and push my updates to Github and not only does it get published it also commits to my repository.

  • Writing posts doesn’t require any fancy tools - since everything is written in Markdown, I can use any text editing software I want. I use Sublime Text, but I could just as easily use Notepad.

  • Like any other hacker, I wanted to learn something knew.

It’s unlikely all of these points will resonate with you, but it’s likely that a few will.

A Few Tips on Migration

So, now that you understand my motivation, let me share a few of the things I did to make the migration from WordPress to Jekyll easier.

  1. Use a Mac. I hate saying this, but the reality is that this entire process will go easier if you use a Mac. I have tried twice in the past to migrate and failed both times from a PC. Even now that I have the migration complete I find that I’m unable to run the command …

     bundle exec jekyll serve --watch

    … on the PC and get it to create the static files as it will fail to properly convert the markdown files. This works perfectly fine on both the Mac as well as in the Github Pages.

  2. Use ExitWP. I performed my migration against a WordPress export file. Originally I used the Jekyll importer for Wordpress but found that it did not do a good job of converting my HTML into markdown. I dug around a bit and found ExitWP - it ran like a champ and did a fantastic job of creating the markdown files. Simply clone the repository and use your WordPress.xml export file.

  3. I decided to use Jekyll Bootstrap as the starting point for a few reasons:

  • I love the simple elegance of Bootstrap, and it was already baked in.
  • It’s 100% compatible with Github Pages.
  • There are some nice Liquid templates for common things like Archives, Categories, Tags, and so forth.

All this said, Jekyll Boostrap also had a ton of code for tools and includes that I'll never use. I ended up spending a good amount of time removing and triaging much of the code. I like it simple and neat. You can take a look at my repository for inspiration.
  1. My blog has a lot of code snippets. Even though ExitWP did a good job of converting my HTML to markdown, I found that most of the code snippets did not get converted well. I’ve spent a decent amount of time going through the posts and updating. To make my life simpler, I decided to use Webscript and some simple jQuery code to give my readers the ability to notify me of a page with bad formatting.

    To implement this I simply created a link at the top of each blog post.

    When clicked, I perform a simple post to my Webscript …

     $( "#target" ).click(function() {
       $.post('', {
           url: '{{ BASE_PATH }}{{ page.url }}', submittedDate: new Date().getTime()
         }, function (data) {
           // capture response
       alertify.alert("Thank you for letting me know! I'll try to get this fixed ASAP.");

    … and then thank the user (using alertify.js).

    In my Webscript I store the URL in a JSON file. I have a second Webscript that will return the JSON file and show me all the URLs posted by users.

  2. It was important for me to migrate all the comments people have made over the years. The easiest way I found to do this is to setup an account with Disqus, use their tools for migrating Wordpress comments into Disqus, and then use Disqus as your comment system.

  3. Ensure that your URLs are consistent so that pages indexed by search providers still work. I simply updated the _config.yml file so that the permalink is defined like this:

     permalink: /:year/:month/:title/

I’ll dig into the topic of deeper in a separate post. is a fantastic tool that you should look into using - especially if you have a static website and don’t want to host your own Web APIs. Suffice to say, this is an easy / simple way to use crowd-sourcing to help me identify posts that need to be fixed.

Aside from the above, I haven’t done all that much. I love having all my code accessible and find that I spend more time experimenting with things I’d never do on Wordpress.

Hopefully this post explains my rationale for migrating to Jekyll and gives a few tips to help you, should you also decide to make the move.

I hope this helps!

comments powered by Disqus