Having decided to move this blog from Tumblr to Octopress, there remained the matter of migrating it¹.

Octopress is basically a convenience framework around Jekyll, adding a nice-by-default theme and some convenience wrappers for starting new posts, invoking Jekyll to generate the site, and deploying the site. You could probably use Octopress quite happily without touching Jekyll directly, unless you want to import an existing blog; then you end up at Jekyll’s Blog Migrations tool, which has options for a number of popular blog engines, including Tumblr.

The instructions for setting up Octopress are pretty simple and well documented:

• git and ruby (and probably rvm or rbenv) are prerequisites
• obtain octopress itself via “git clone”
• install dependencies via “gem install bundler; bundle install”
• install the default Octopress theme (which also generates the skeleton site layout) via “rake install”

At this point, you’ve got a working Octopress installation and you could use its rake task-based interface to write and publish posts. However, if you want to migrate an existing blog, you have more setup steps which are also well documented:

• assuming you want to keep your raw posts in markdown format instead of raw HTML, Jekyll’s Tumblr migrator needs nokogiri: gem install nokogiri
• invoke the Tumblr migrator:ruby -rubygems -e 'require "jekyll/migrators/tumblr"; Jekyll::Tumblr.process("http://www.your_blog_url.com", "md")' Note that this doesn’t require any account information or credentials, because the Tumblr API will provide enough information to do this anonymously. Heck, if you’re evil, you could convert someone else’s blog (don’t do that). On the topic of Tumblr reliability, I ran this step a few dozen times while I was figuring out how it works and fixing some bugs in tumblr.rb, and ~90% of the time, it downloaded my ~165 posts almost instantly, but palpably often, it would get stuck halfway as the Tumblr API stopped sending it network traffic. Oh well. Ctrl-C and restart if this happens to you.

What neither the Jekyll nor Octopress documentation tells you is what happens next. Assuming you run all the above commands from the octopress directory: Octopress setup (the rake install step) created a directory called “source”, under which the (initially empty) “_posts” directory is where Jekyll will look for posts. Meanwhile, Jekyll’s tumblr.rb will create and populate a “_posts/tumblr” directory with your posts, and a “posts” directory with redirects from the old Tumblr-style post URLs to new Octopress-style URLs²,³. Neither the “_posts” nor “posts” directory spit out by tumblr.rb are under “source” where Jekyll will look for them. What this means is that without additional effort on your part, Jekyll as invoked by Octopress won’t see the files you just imported.

Again: your blog posts go in “octopress/source/_posts”. The Tumblr migrator will create “octopress/posts” and “octopress/_posts”. Just move these two directories under “octopress/source” once you’ve verified they look OK. (NB: the migrator actually dumped all its files under “octopress/_posts/tumblr”; it’s fine to leave them there, so they end up in “octopress/source/_posts/tumblr”; Octopress doesn’t seem to care about the organization of your files inside the source/_posts directory.)

Now, you can tell Octopress to generate the site: “rake generate”.

If you’re reading this at the right point of relative stability, lucky you; you win. I ran into several more issues, due to the fact that Jekyll and Octopress are prerelease open source software intended for an audience of hackers; some assembly definitely required:

• At the point I was performing this migration (January 2013), Jekyll was at version 0.12 and the tumblr.rb migrator script was broken in a couple respects which I submitted patches for.
• After my patches were merged upstream, I tried running with Jekyll’s head version in mid-February, to find that tumblr.rb had been deleted from the Jekyll repository entirely, and moved to a separate jekyll-import project, which at the time had no documentation and appeared to have little chance of running.
• Meanwhile, using any version of Jekyll newer than 0.12 broke Octopress in a trivial way; the :generate rule in Octopress’s Rakefile finishes by invoking Jekyll as system 'jekyll', with no arguments, and newer versions of Jekyll expect a build argument. Octopress will fix this when Jekyll actually releases a new version (which may have already happened between me finding this and posting this); it makes no sense to fix it sooner.

This last list of foibles is probably all related to Jekyll being in the throes of the 1.0 release process and will probably be a historical footnote afterwards.