Mind maps with

Keep your |
organized in a mind map

Moving from Wordpress to Jekyll

Just moved this blog from Wordpress to Jekyll.

Previously, I was using a shared hosting server to run this blog on a Wordpress + MySQL combo. That worked well and it stood solid for the kind of traffic that I usually get (~30K pageviews/month).

But being a web developer, I always wanted to run my own web server and host my blog there. Hence the move.

Now what you read is proudly served from a Linode machine by a Nginx server with the static HTML pages generated by Jekyll and version controlled at Github. Neat, huh!?

The move was not easy though. I had around 300 posts in my wordpress. Some of the posts are not so much useful or became obsolete now. So, I had to to nitpick which one to move to the new platform. Google Analytics helped a bit to decide on the top performers. I kept my own favorites untouched. Rest of the posts were axed.

Also, the Wordpress to Jekyll converter plug-in did a good job of reformatting my blog posts to suit the Jekyll structure. But it messed up with some of the posts and I had to manually skim thorugh the content to fix things up. So, if you see any formatting issues, please let me know about it and I'll fix.

As part of passing the knowledge torch, here's the list of steps that I did to switch the blogging platform.

How you can move from Wordpress to Jekyll?

First of all, if you new to Jekyll and you are confused with the offical definition 'Simple, blog aware, static site generator', here's my version of explaining Jekyll to you (either to confuse you more or give you a clear idea).

Jekyll is a program written in Ruby. Unlike Wordpress, you run Jekyll in your local machine, not on your web server. Unlike Wordpress, Jekyll does not give you admin panel or anything. Unlike Wordpress, you do not need a MySQL database to store your post content. Unlike Wordpress, you can't simply upload images and expect them to be available for your posts. You need to host images in somewhere else (or your own server) and you need a URL to include it in your posts.

All Jekyll does is that it converts your posts, mixes them with template files and finally generate a static, plain, old HTML files which you can host at any web servers.

Jekyll is not for weak-hearted.

If you are familiar with JavaScript templates such as Mustache, Dust in which you define templates with placeholder for data and you pass JSON to prepare the final content, Jekyll is exactly that - you define your page structure (templates) with placeholders for content and you write your posts. When you run Jekyll, it will insert your posts in the placeholders and spit out complete HTML files.

So, here's what you should do if you want to switch.

Phase 1: Install Jekyll in your local machine.

  1. Install Ruby.
  2. Install Jekyll.
  3. If not already done, Install Git.
  4. Clone any existing Jekyll sites, so that you don't need to create everything from scratch. Tom Preston-Werner is a good starting. Here's mine, forked from Tom Preston's and modified to suit my blog.
  5. Get familiar with the Jekyll folder structure.

Phase 2: Convert Wordpress posts to Jekyll posts.

  1. Take backup of your current wordpress blog (very, very important).
  2. Install this plugin - Wordpress to Jekyll exporter - zip file.
  3. In Wordpress admin panel, go to Export and export your posts to Jekyll. The plugin will create a zip file which will be downloaded.

Phase 3: Create your blog in Jekyll

  1. Copy the converted wordpress posts (which are in Markdown format) to Jekyll's _posts folder.
  2. Familiarize yourself with Markdown syntax.
  3. Make sure the content of your posts are properly formatted in Markdown. If you had code block in HTML, XML then you'll definitely have problems. Review those posts once again and copy the correct content from your backup.
  4. If you are using Windows and your posts are in UTF-8 encoding, make sure the files do not have BOM character in its header. If BOM is there, then Jekyll conversion will not work as expected. You can use UTFCast to convert your files to UTF-8 format with out BOM (make sure you uncheck write BOM while converting).
  5. Go wild and design your blog as per your taste. Run Jekyll in auto refresh mode to see the changes you make immediately reflected in browser: jekyll --auto --server.
  6. Once done, the final blog will be available in _site folder. Take the content and host them anywhere you want.

Phase 4: Version Controlling & Auto publishing.

So far, if you make any changes to your blog, you have to manually FTP the changes to your hosting server. But there are nice tricks available that helps to automate this step. Use them and create awesomeness.