From WordPress to Jekyll

If you are a return visitor to my blog you might have noticed that it recently became faster - quite a bit faster, actually. This is because I finally put in the effort to migrate from WordPress to Jekyll. This blog is now entirely hosted on Amazon S3 and served via Amazon Cloudfront.

I am writing this post to serve as a migration guide and general signpost for those who are considering switching to Jekyll - be it from WordPress or another platform.


I had been using WordPress for about 3 years, and it really is a great platform for blogging. My main gripes with it were:

  1. Performance - even though my blog is very close to a static site I found the performance rather sluggish (despite using caching Plugins on WordPress).
  2. Hosting - I was using BlueHost - which was ok - but I definitely didn’t understand the entire stack and I didn’t have full control. I had this nagging feeling that I would need to switch at some point and that would require a much greater knowledge of WordPress and PHP than I had.
  3. Security - given my lack of knowledge of WordPress I was very reluctant to install any plugins (which seems to be the main cause of security holes) and I was very unsure about the security of the platform in general.

On the other hand, Jekyll looked like a great solution for a few reasons:

  1. It’s written in Ruby, which means I understand the technology and I can write my own plugins if needed.
  2. It generates a static website, which means much better performance and it can be hosted on S3 / CloudFront.
  3. It supports MarkDown, which is what I was using to write blog posts already. (On WordPress I had to first convert it to HTML and then go paste it into the HTML editor)
  4. Syntax Highlighting with Pygments. I had been using SyntaxHighlighter on my WordPress blog, but I didn’t like that I needed all this JavaScript to generate the code snippets. (Plus the results don’t look nearly as good as Pygments)
  5. Generating my blog locally means I can put everything under source control - something which has been bothering me about my WordPress site.

Overall it looked very appealing.

Export Content From WordPress

This first thing I did was to get my content out of WordPress. There is a very handy plugin called WordPress to Jekyll Exporter which exports all of your blog posts and pages to MarkDown format.

I had to do quite a bit of cleanup on the export, but most of this was due to having moved from Blogger to WordPress - many of my posts were a complete mess! I was also using Picasa to host my images - if you think this sounds like a terrible idea, you’re right - so I had to write some inventive scripts to curl these to local files which could be hosted directly in Jekyll.

Setup Comments

One of the downsides to Jekyll (for me) is that I had to say goodbye to comments. (Well, hosted comments anyway). Many members of the Jekyll community don’t do any comments (which I find rather lame), but the majority seem to use Disqus (which is obviously what I’m doing right now as well). I’m not crazy about this solution - especially because Disqus doesn’t let you style your comments - but I don’t have any better options at the moment. (I would really love a competitor to Disqus that lets you style your comments)

Migrating your comments from WordPress to Disqus is really straightforward, just create an account, install the Disqus plugin and then start the export (on the Disqus website). It takes a couple of hours to complete.

Setup Jekyll

Jekyll is packaged as a Ruby gem, which means we can install and manage it with bundler. I also wanted to create a separate gemset for Jekyll and use rvm to manage the ruby version.

mkdir jekyll
cd jekyll
echo 'jekyll' > .ruby-gemset
echo 'ruby-2.2.0' > .ruby-version
cd .
bundle init

Now you should have a Gemfile to which you can add the jekyll gem. The last step is to run

bundle install

Now we can use jekyll to generate the new site (which will be a folder under your jekyll folder).

jekyll new
jekyll serve

If everything went well you should now have a new jekyll site up and running and available at localhost:4000. I would strongly recommend that you create a git repository at the root of your website folder and maintain everything under source control.

Now you can copy all your exported WordPress content into the _posts folder of your new site. Jekyll will automatically recompile your site as you add or modify content. The Jekyll documentation is excellent and will help you configure all the different areas of your new site.


Once you have your Jekyll site styled and configured the way you want you will need to decide where you want to host it. Github offers free hosting for Jekyll sites and is a very popular option. I decided to host my site directly on Amazon S3 - I am very familiar with S3 and I wanted to be able to control all aspects of my blog.

I basically knew that I wanted to put the content on Amazon S3, have it served via Amazon CloudFront and manage the domain configuration on Amazon Route 53. For the most part I followed the instructions on this blog, although I had to switch my domain name from GoDaddy to Route 53 as well.

Amazon also allows you to host your website at the root of your domain (so at instead of This meant I had to create an additional bucket that redirects www requests to the root domain, but this is all really simple.

Jekyll basically builds your entire site into the _site folder, which can then be copied to your S3 bucket. To do this I use the simple-s3 gem - you can find a quick guide on how to use it here. This gem has support for CloudFront, so it will automatically invalidate your CloudFront distribution as part of the deployment.

Once you can access your site via your CloudFront URL you are basically ready to pull the trigger and point your domain at CloudFront. This is particularly easy if you’re using Route 53, since Route 53 automatically provides you with the option to select a CloudFront distribution when configuring your domain.

Pain Points

The biggest pain point in this entire process was my RSS feed. I had originally published my RSS feed via FeedBurner, which I have now come to regret. I tried to update FeedBurner with my new feed address, but unfortunately FeedBurner refused to make this change and I ended up losing all subscribers. (If you are a subscriber and you would like to stay subscribed, please update your reader with the new address.)

I knew this was a possibility in doing this change, but ultimately it seems rather unavoidable. In any case, I knew I had to migrate away from FeedBurner at some point (since it hasn’t been maintained) so maybe it’s better to take this pain now rather than later.

Overall Impressions on Jekyll

Overall I am really happy with Jekyll - the documentation is really good, the technology is really solid and straightforward, code snippets look great thanks to pygments - overall it’s just a great platform.

Long-term hosting on CloudFront / S3 is a much better choice - and more affordable. The performance is excellent and the whole site feels really snappy. The only area that I might look into changing is the comments - I’m simply not that happy with Disqus and I would really like to find a better solution. Happy coding.