NOTE
This article should be considered archived. No further updates are expected. For ReST-flavoured blogging, please see Pelican.
A Story of Markup
Jekyll, by default, does not support writing your static page/blog in Restructured Text, or ReST. I came at my personal projects from the Python world, where ReST is commonly used. I, therefore, am much more comfortable in the ReST world than am I in the Markdown or Textile. Naturally, I went looking for a Jekyll RST plugin. There was only one I could find, and it was sufficiently old as to no longer work with modern docutils setups, so, rather than tie myself down to an ancient docutils, I decided to modernize it.
A Story of Dependencies
The github repository I found listed as dependencies Pygmentize and Docutils. It turns out, however, that the important parts of both projects were included in the repository itself. Seeing this as a waste, I first remove Pygmentize, discovering to my joy that the docutils converter I was using would do that for me! I then set about removing the glue that tied that Pygmentize to the rst2html in the repository. Simple, and it Just Worked™. Now that I was here, with a bog-standard rst2html, I tested things. Nope, UTF-8 conversions weren't handled automatically in this wrapper class. No problem, let's just bring in the modern one. Wait, what? If I'm directly including the modern one, and also listing it as a dependency, it would be much cleaner to just use the version brought in, no? So it went away, leaving just the ruby=>python bridge. Much cleaner, if a bit of a trivial product now.
A Story of Gems
Ouch! There was a ticket on the original project I forked asking for it to be made available as a gem. I'm a sucker for interesting projects, so I set about to make it so. Create a branch, switch to it, and get on with the gem creation! Except, no. There's multiple different educational resources each containing the correct instructions for the version of gem and bundle that were current when they went live. None of these versions were anything resembling current, so I'd have to go deeper. I'd have to go to the source of truth about these topics, the official documents at the Bundler itself. This got me bootstrapped with, ironically enough, a bootstrap routine. A few more tweaks of configuration, and I could build a gem. It was just a shame that it did nothing at all...
A Story of Reference
By gum, somebody had to have done this before me! I checked out the Jekyll site again, and sure enough they released one of their official parser/converters at the Textile github repository! Thanks and praise be to the gods of documentation! Anyway, I adapted their configuration to match the code I already had, using the Ruby underscores naming convention (though this is purely a aesthetic change, as I consider this its own thing and they consider theirs an extension). I also had some Jekyll plumbing to adapt. Luckily their code is MIT license` and so is mine. A few code changes and framework force-fitting and I'm off to the races!
A Story of the Future
Where do we go from here, my dear readers? That's a good question. The inclusion of the plugin is now dead-simple, so we could just let it be. We also could include it in an official Gems repositories, or one of the Jekyll plugin repositories. These decisions await a more permanent answer in the future™.
TL;DR
Go to this repository and get blogging in rst files.