Migrating from WordPress to Octopress

Main Thread 3 min read

This past weekend I migrated my blog from WordPress to Octopress. Before I explain the migration, let me explain why I migrated away from WordPress.

First, I am a fan of WordPress. I've written many posts on WordPress, spoken at WordCamps, and will continue to develop with WordPress. But WordPress is slow. And I had a need… a need for speed. Greasy, fast speed.

Enter Octopress:

Octopress is a framework designed for Jekyll - the blog aware static site generator powering Github Pages.

GitHub uses it — that's reassuring. Static site — you don't get much faster than serving a static resource. Look for a follow-up post with the performance showdown between Octopress and WordPress soon.

I also wanted something simple. I don't use all the features of WordPress. I just write posts from time to time. From the beginning I've drafted my posts in Markdown. Jekyll uses Markdown in its templates. Simple.

You may be wondering the difference between Jekyll and Octopress. Jekyll is tool, Octopress is the packaging. Octopress nicely wraps some of the rough edges of Jekyll making it easier to manage. It also offers themes and plugins.

Now if, like me, you're sold on Octopress read on. If not, thanks for reading this far. Long live WordPress!

Migrating from WordPress to Octopress

Here is an outline of the steps for migrating from WordPress to Octopress with more details below.

  1. Installed Octopress
  2. Migrated Content from WordPress
  3. Previewed Site
  4. Deploy Octopress

Installing OctoPress

For the most part, I followed the Octopress Setup. The only exception being Ruby. I'm on Mac OS X Mountain Lion. So my Ruby version was 1.8.7. I updated Ruby with RVM.

curl -L https://get.rvm.io | bash -s stable --ruby

Migrating Content from WordPress to Octopress/Jekyll

There were several migration options. I tried a few of them and found Export to Jekyll best as it ran content through the approriate WordPress filters. While Export to Jekyll was the best of the bunch, it wasn't perfect.

  • Encoding issues. After moving the files from Export to Jekyll rake generate erred about gsub. The issue was UTF-8. With some debugging, I found several UTF-8 characters in my posts. Mostly smart quotes and other artifacts like EM dashes from Mac OS X. Unfortunately I didn't find a quick fix. I ended up replacing these with HTML entities using some sed commands. This was the worst part of the migration. And it wasn't that bad.
  • Missing meta data. Aside from the title, none of the WordPress SEO settings were exported. I wrote a PHP script to add the description and keywords to the Front Matter. I will likely fork Export to Jekyll soon. If you're interested in these, please leave a comment.
  • Misconfigured comments. The export did not set comment in the Front Matter. I fixed this with a quick sed command as all my posts allow comments. However, this is something Export to Jekyll could have done.
  • Exporting comments. I migrated my WordPress comments to Disqus. Suprisingly simple. But Disqus took several hours to process the import (130 comments).
  • Static resources. I needed to download the static resources in my content (images, PDFs, etc). This is not necessary if you use a static domain. But if you use WordPress uploads/, you'll need to download them to Octopress source/. I wrote a curl script to do so.

Deploying Octopress

Octopress has a few automated deployment options. I used rsync. However, my blog runs on Amazon EC2. So I needed to configure my EC2 private key to deploy Octopress. After doing so, I deployed to Octopress to my Amazon EC2 instance by simply typing rake deploy.

Blogging with Octopress

Octopress is not without its own challenges. I found limited SEO out-of-the-box and I will need to learn the nuiances of Octopress themes. Look for future posts on both.

Nonetheless, with Octopress I can write like I always have. I don't have to manage WordPress upgrades or plugins. I don't have to make WordPress faster. I just write. This frees up my time for other things.

Find this interesting? Let's continue the conversation on Twitter.