Writing long documents in a browser input box isn’t the most pleasant thing to do. The WordPress builtin editor makes things even more inconvenient by forcing you to write your articles in HTML. It would be pretty cool if you could edit articles in a simple, readable format using your favorite text editor. Fortunately, there’s ReStructured Text, a document format frequently used in the Python community.
ReStructured Text (rst) is a pleasant plain text format that can be converted into different formats like HTML or LaTeX. The format is pretty intuitive and well suited for typical blog postings with a bit of formatting and a few links (see this example). Of course, there are also more powerful features, but I don’t use many of them in my articles.
The rst distribution comes with several converter scripts, but none of them is perfectly suited for WordPress. The HTML syntax WordPress uses is slightly simplified and we need just the body, not a full HTML document. Using the rst2s5 converter as a reference I wrote my own converter: rst2wp.
The rst distribution contains a library that parses the text format and turns it into a document tree. A writer class then translates the document tree into a writer-specific format (HTML, LaTeX, S5, …). All I had to do was to inherit from the standard HTMLTranslator class and override all parts of the document I wasn’t interested in. The HTMLTranslator follows the visitor pattern so it’s pretty easy to understand.
rst2wp my workflow for posting an article works like this:
- Write the article in rst format.
- Check it into my Mercurial repository.
- Run rst2wp to turn the article into HTML.
- Paste the output into the browser’s input box.
The script works well for me, but I didn’t test the more advanced features of rst so there’s a good chance that they won’t work. Feel free to tweak the script to your needs, the code is pretty simple. A possible next step would be to write a tool for posting the article directly via WordPress’ web service. But I’ll leave that for another day.