How To Migrate Your Blog From Wordpress To Jekyll

To be aligned with the new design of our marketing site, our blogs have been redesigned with the same theme. More importantly, they have been also migrated from Wordpress to Jekyll. Jekyll is a blog-aware, static site generator in Ruby. We have wanted to move to Jekyll for a while now since it is so better than Wordpress in terms of speed, security and ease of maintenance. Also since all of us at SupportBee are hackers, we find it much easier to use git to push content than to use TinyMCE. Here are the steps that you can take to migrate your Wordpress blog:

Install Jekyll

It is amazingly simple to install Jekyll if you do it via RubyGems. A simple gem install jekyll does the trick. At Supportbee, we like to use Jekyll-Bootstrap which gives us more blogging tools like disqus etc out of the blog. You can find the installation guide for Jekyll-Bootstrap here.

Export Wordpress content to XML

Then, you will need to export your wordpress blog content to an XML file by going to your Wordpress admin page (

Converting the imported posts to Markdown

Make sure you have hpricot gem or install it using gem install hpricot.

Assuming the export is called wordpress.xml, run the following command in the terminal

$ ruby -rubygems -e 'require "jekyll/migrators/wordpressdotcom"; Jekyll::WordpressDotCom.process("wordpress.xml")'

Now when you try to run jekyll --server --no-auto after putting the imported posts inside _posts/ folder, there might be some errors. The problem is that there are mixed UTF-8 and ASCII encoding in the posts thanks to wordpress. Replacing these characters can be a real pain in the neck. We are going to save a lot of time for you with the following script.

Just put this convert.rb file in the same folder as your converted posts and run ruby convert.rb in the terminal. Ta da! Now you’re good to go. You might want to start jekyll server on your local machine and go through the posts to see if they are displayed properly.

Deploying Jekyll

We deploy Jekyll on our own servers using Capistrano. We use set :deploy_via, :copy strategy, which will generate the _site locally and copy that over to the server.

Jekyll is built for Github Pages. But this is bad news if you are using Jekyll Bootstrap(JB) with custom plugins and deploying on your own setup instead of Github Pages.

In JB, you can configure the BASE_PATH with the path to the server. When _site is generated locally using jekyll --server, the BASE_PATH is ignored. You have to run jekyll --safe for the BASE_PATH to be considered. Unfortunately adding --safe will not include the custom plugins.

To generate the correct server _site locally, we add a Rails-like environment variable to _config.yml. Also set JB.setup.provider to custom

Add the following file which loads the BASE_PATH properly based on the environment

Also JB checks for in a few places. We replace this condition with site.env == 'production'

And finally, add the following to the Capistrano’s deploy.rb

blog comments powered by Disqus
Anh Do
Anh Do