I’ve been contemplating leaving WordPress for a while. Part of it was a desire for something simpler, part of it was that as I worked on Hieroglyph, I found myself really appreciating the Sphinx build pipeline. Older blog posts on my site have also been in varying states of brokenness for the past few years: I used to use Textile for writing posts, but at some point the WordPress plugin I was using stopped working, so I just let it serve them with the raw markup. It felt like it’d be easier to fix those up into something sane if I had flat files to work with, instead of a relational database.

There are quite a few static site generators these days, but only one that I’ve found that leverages Sphinx. Tinkerer leverages Sphinx, adding an extension for aggregating post pages into archives, categories, and tag pages. Its use of Sphinx means that you can also generate non-blog pages with it, and you have quite a bit of flexibility to extend it if you need to.

Moving from my WordPress backend, I wanted keep the URLs as stable as possible. Tinkerer 1.0 is great, but it did a few things differently than I’d like. Specifically, it:

  • uses the Sphinx HTML builder, which adds .html extensions to the output pages
  • assumes that the blog’s root is the root of the domain (on my site it’s in the /blog/ path)
  • places every post in your RSS feed
  • doesn’t allow you to configure the output path for the feed or archives

I’ve forked Tinkerer on Bitbucket and addressed those issues. Making Tinkerer work with the dirhtml builder was most of the work, as there were several places that assumed you were dealing with HTML files (instead of directories with an index.html inside them). My experience with Sphinx from Hieroglyph came in handy here: the Sphinx HTML builders all have a .get_target_uri() method, which does the right thing. I’m sure there are some things I’ve missed or broken in the process, but my hope is that I can get my changes into shape and merged upstream. I’ve also added several configuration directives for customizing how Tinkerer works. I still need to update the documentation in my fork, but you can see those in the source.

As an aside, if you’re looking at migrating from WordPress to another platform, the exitwp script is a pretty sane place to start. I used it, along with pandoc, to transform my WordPress export into more uniform Restructured Text.

author:Nathan Yergler
tags:sphinx, tinkerer, rst