Switching To Octopress

Posted on Thu 24 January 2013 in Dispatches • 6 min read

This site is now powered by Octopress. The tentacles compell you!


It’s tentacly delicious!

As I mentioned in my previous post, I’ve been looking to try out a new CMS for this site. The reasons were myriad, and they were all discussed in the aforementioned post, so I’ll avoid rehashing them. Essentially, my custom Django-powered site was very much behind the times in development and it was clear I wouldn’t be able to put in the time to correct it. I laid out what I was looking for, and asked for feedback from readers.

I received a few suggestions for simple hosted solutions such as Squarespace, which is a great service, but I really wanted to self-host my site if at all possible. Also, my experience with other services has been that import/exports are never as simple as advertised. At least, they aren’t that easy if you are a geek with a propensity to try strange new engines that they never anticipated1. So I moved on to more established blogging engines, but none of them were exactly what I was looking for in a new CMS.

Somewhere along the way, it occurred to me that at least half of my problems come from the fact that I’ve been using all these dynamic features for a site that I don’t update all that often. It was around this time that I received the following recommendation:

@andrlik You should try a static site generator like http://hyde.github.com


The Curious Case of Jekyll and Hyde (and a cephalopod)

Hyde was really appealing to me at first. It’s a Python static site generator, and uses Django/Jinja2 templates, which I was already experienced in using. Unfortunately, the documentation for Hyde is ridiculously bad; I couldn’t even figure out where I should start, and most of the more comprehensive tutotials and examples were for a two year old version of Hyde, which didn’t match the current codebase. Even if I successfully set up an effective Hyde project, it looked very likely that I would be writing helper scripts to produce a sane workflow for blogging, which was counter to the goal of “code less, write more”.

As it turns out, Hyde is the “evil twin” of a Ruby static site generator named Jekyll. The latter’s documentation is significantly better, and looked to have a very active development community. However, it’s Ruby2, and it also didn’t have the kinds of helper scripts I was looking for to help streamline the writing process. I was just about to give up and return to dynamic options when I came across Octopress.

Octopress is a framework built around Jekyll that automates and streamlines many of the day-to-day processes for a user. For example, it has built-in scripts for automating the creation of new post/page files, previewing drafts in isolation, and tons of helper plugins for common display requirements. It also has baked-in integration with popular sharing services and an active plugin and theming community. Since it is based on Jekyll, it also benefits from the coding community there. What I liked most about Octopress is that it looked ready to go, with an attractive and functional theme that I was able to start using without too much hackery on.

I’m also a fan of the plugins that make it really easy to create beautiful pull and block quotes using only CSS, as seen above. That’s the kind of thing I would have to hand-code in another environment, but I love that I can create them as easily as this:

{% raw %}
{% pullquote %}
{" Octopress is a framework built around Jekyll that automates and streamlines many of the day-to-day processes for a user."} It also has baked-in integration with popular sharing services and an active plugin and theming community. Since it is based on Jekyll, it also benefits from the coding community there. What I liked most about Octopress is that it looked ready to go, without too much hackery on my part.
{% endpullquote %}
{% endraw %}

I love the simplicy of the system. It can easily be backed up as a git repository, and it’s all static files, so it serves ridiculously fast. As a result, it can be hosted anywhere. It didn’t take me long to export all my entries from my old site into json files, and from there it was trivial to write a python script to parse them all into Jekyll-compatible markdown files. Most of the work after that was tweaking the themes and testing.

Side Effects May Include…

Of course, not everything is hugs and rainbows. There are some problems with Octopress/Jekyll that I uncovered during this process. Let’s address those head on.

Regeneration Takes A Long Time

Don’t let anyone tell you otherwise, if you have a lot of posts, expect site generation to take a couple minutes to complete. I have close to a thousand posts of varying lengths, and it takes several minutes to regenerate my whole site. It would be nice if there was an option to incrementally update the site, so as to avoid having to do the whole project each time. I realize that this is not as simple a problem as it sounds, but it is an annoyance.

Octopress helps here as it provides tools to isolate regeneration during drafting of specific posts. As a result, I can have instantaneous updates to this post while I write it by running the following commands.

$ rake isolate[switching-to-octopress]
$ rake preview
# When I'm done, I can switch back to the whole site by running.
$ rake integrate

I can live with that as a workaround, but it’s mildly annoying.

The default related posts functionality only retrieves the most recent posts. To do any kind of semantic indexing you need to make use of the LSI feature, which is slow, slow, slow. It worked great when I was just working with a few test posts, but for my full archive I could never get it to finish, and that was after letting it run for hours. This kind of index building took less than a minute using the Xapian backend on my old Django site, and it cached the results. The index for Jekyll needs to be rebuilt each time, so there is no way I’ll be able to make use of it.

Now, I don’t know how much value the related post feature actually adds anyway. Looking back at my analytics from before, it seems people where more likely to click the pagination and tag links more than anything else, but it’s irritating. I’d love to see a Ruby guru put together a Xapian based version of this, as it should be much faster.

On my old site, I used month abbreviations in my permalinks, e.g. “jan”. It made for very attractive urls, but while you can slice and dice permalinks in a lot of ways, ultimately date-based permalinks have to be numerical. That was annoying, but nothing I wasn’t able to fix with twelve nginx rewrite rules.

One Node Only

This was by far the most frustrating thing. While you can have any arbitrary number of free-form pages, the blogging functionality in Octopress/Jekyll presumes that it will all fall under one node, such as /blog. My previous site seperated my actual entries from my link blogging using the /writing and /links nodes respectively. I’ve seen accounts of people daisy-chaining multiple Octopress installations together to achieve this, but down that way lies madness.

Instead, I’ve opted to import my links as entries and deferentiate them using the “♺” symbol. This presented a challenge, because of legacy reasons from third party imports, my old site was using either a third-party short name or a hash of the url. That was ugly, and I decided to switch to using title slugs. Then, to ensure that any canonical links didn’t get lost, I used my Python converter script to generate the 669 rewrite rules required to ensure that anyone using the old links finds their way to the correct address.

It was an ugly way to migrate, but honestly after wrangling with it for a few hours, I’m happy with the final solution.

In The End

Despite all these issues, I’m really happy with Octopress so far and I’m looking forward to seeing what else comes out of the project. I’ll likely continue to tweak the look and feel of the site over the next few weeks, but I think it’s safe to say that I’m all in on Octopress as my next publishing platform.

  1. Like a custom Django CMS for instance. Octopress doesn’t count as difficult since it is just Markdown files. 

  2. I prefer Python, sorry. Your hate mail is delicious.