Migrating from WordPress to Octopress

For some time I have looked at moving away from Wordpress for numerous reasons (That would be for another post!). I took a look at various platforms, but most fell short of expectations. Either they were too bloated, troublesome to manage or they lack some core features. I played around with Jekyll and I liked the initial idea. But, after doing more research I found Octopress and I was quite happy with the final result.

Since you can host your blog from GitHub pages, my original plan was to first get a working copy running. After everything looked well, I would point my domain name to GitHub. This is how I did it...

First Step: Get all data out of Wordpress

This step was easy, just log-on to Wordpress' admin page and initiate an XML export. This is optional, but for the database export I decided that it would be easier to just do a MySQL dump and then do an import on my local MySQL instance.

All of the static files will need to be moved. If you are hosting them somewhere else you will only have to worry about the wp-content folder. This folder contains all of your plug-ins, themes, and images. In reality all we need is the images, in my case I deleted the rest except the images which were under the uploads folder.

Install Octopress

Again, this step is easy and very well documented. If you are hosting on GitHub you will need to create a new repository that follows the correct naming convention.


For example, my repo is dyurk.github.io.

Importing your data to Octopress

You will need to install the jekyll-import gem:

$ gem install jekyll-import

In the directory where you have your wordpress.xml file run the following:

$ ruby -rubygems -e 'require "jekyll-import";
      "dbname"   => "wordpress_db",
      "user"     => "user",
      "password" => "pass",
      "host"     => "localhost",
      "prefix"   => "wp_",
      "clean_entities" => true,
      "comments"       => true,
      "categories"     => true,
      "tags"           => true,
      "more_excerpt"   => true,
      "more_anchor"    => true,
      "status"         => ["publish"]

This will create a _post directory. Which will need to be move to octopress/source/.

Keep in mind that any <code> tags will need to be replace by backticks. Any snippets or tags specific to Wordpress will most likely break formatting.

Finally, for the static content in the wp-content folder, I decided to move the entire directory under octopress/source/. That way I don't have to update the code and SEO does not take a hit.

Custom domain and 404s

If you own a domain that you would like to use for your GitHub hosted blog. Basically, all you need is an A record pointing to and a file under octopress/source/ name CNAME. In this file add your domain name like so:


To gracefully handle 404s I decided to redirect to the homepage. To add a custom 404 page just create a file under the source/ directory. The file must be named 404.html. Here is my file:

        <meta http-equiv="refresh" content="0; url=http://dyurk.com/" />



After the DNS changes take effect the blog should be accessible via the domain name. If you are looking to customize your blog I recommend reading Octopress' documentation on the topic: http://octopress.org/docs/theme/.

As a side note, if you need to moved your working copy to a new computer or just need to re-create it, you will need to do the following:

Clone the source branch:

$ git clone -b source git@github.com:username/username.github.io.git octopress 

Bundle install and setup GitHub pages:

$ gem install bundler
$ sudo gem install bundler
$ rbenv rehash && bundle install && rake setup_github_pages

Now fetch the master branch:

$ cd _deploy
$ git fetch —all
$ git reset --hard origin/master

Tagged under: wordpress, octropress, GitHub, pages