Migrating from Octopress to Jekyll

Main Thread 2 min read

Over the years, this blog transitioned from a custom CMS to WordPress to Octopress and now to Jekyll. Each migration has been an invaluable learning experience.

In the process of redesigning this blog, I made the decision to migrate from Octopress to Jekyll.

Now some of you may be thinking - isn't Octopress Jekyll? Why transition to Jekyll?

First, let me say I have nothing against Octopress. Octopress was my gateway to Jekyll. For that I am thankful.

However, now that I am familiar with Jekyll, I don't need Octopress. In fact, in the authors own words:

Octopress is basically some guy's Jekyll blog [...] released as a single product, but it's a collection of plugins and configurations which are hard to disentangle.

Furthermore, Octopress last release was 2011. While I don't update this blog often, Octopress seems to be dead.

Ultimately the abstraction of Jekyll through Octopress is cost without benefit. Migrating to Jekyll made it easier to find a blog theme and afforded me the opportunity to use GitHub pages.

The Migration

Since Octopress is Jekyll, much of the configuration remained the same. There were variables where I had to cross-reference the documentation. In addition, some of the custom front-matter variables for my posts didn't match my new theme. I wrote a quick script to convert/duplicate variables.

I also lost some of the Octopress specific features, notably:

  • Integration with Disqus
  • Integration with Google Analytics
  • Archive pages
  • Deployment Tools

To be fair, all but the last item have more to do with the theme than Octopress or Jekyll. Nonetheless, I had to rebuild these features.

Adding integration for Disqus and Google Analytics was straightforward. I added some configuration variables to _config.yml and updated the liquid templates in the theme to include the respective code snippets.

The archive pages were not as straightforward. By default, Jekyll does not include a complete archive page with pagination. Furthermore, it does not generate category archive pages.

Within Jekyll you have access to all posts through the site.posts variable. As such, I could create my archive page simply by looping over site.posts.

1{% raw %}
2 {% for post in site.posts %}
3 {% include post_preview.html %}
4 {% endfor %}
5{% endraw %}

I was willing to lose pagination. So this simple loop was fine. If more you can review this and that.

For the category pages I created a Jekyll Plugin. Technically a generator. While the documentation actually contains CategoryGenerator, I ported the Category Generator from Octopress.

Eventually I may deploy to GitHub pages. For now, I deploy to a web server using the following rsync.

rsync -vrz --checksum --delete _site/ server:~/webroot/

Eventually, I'd like to turn this into a rake task. For now, it's easy enough to run.

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