tadhg.com
tadhg.com
 

Blog Workflow with reStructuredText

22:57 Tue 14 Jul 2009. Updated: 23:13 28 Jul 2009
[, , , , , , , ]

I wrote about moving my writing over to reStructuredText on Sunday, and since then I’ve moved both my morning pages and my blog writing to it. The latter proved more complicated, primarily because I wanted to make the process almost as easy as writing pseudo-HTML (which is more or less WordPress’ native format, and kind of mine, too, for the last several years). With some hacky wrangling, I’ve managed to set that up.

I don’t write my posts in the browser. That’s too prone to crashing, and I like my text editor, jEdit, too much for that. On top of that, I want to be able to use Subversion for my posts, as I do for more or less everything I wrote. So for the last couple of years, I would write the posts in jEdit and then copy and paste the finished product into the WordPress new post window.

Since I generally tinker with a few things once I see the post preview, it’s never been worth it to me to try to do automatic posting from the command line, which I know is theoretically possible with WordPress. I thought I might move in that direction given the reStructuredText move, but it didn’t work out that way.

One option was to use the rest-wordpress plugin, which would do the reStructuredText parsing on the blog side, so that my workflow would be to paste the reStructuredText source into the WordPress edit field as usual, and then have it turn it into HTML. While that seemed a reasonable option, I was eager to create some custom directives that would let me make reStructuredText even more useful. Sadly, custom directives aren’t that easy to add in, and I decided that if I planned to develop those, I should do it locally rather than on the server side.

The old workflow was:

  • Write post in pseudo-HTML in jEdit.
  • Select all.
  • Copy.
  • Switch to WordPress new post tab in Firefox.
  • Paste.
  • Fiddle with the post settings slightly.
  • Post.

The new workflow:

  • Write post in reStructuredText in jEdit.
  • Select all.
  • Copy.
  • Invoke a shell script via Quicksilver.
  • Switch to WordPress new post tab in Firefox.
  • Paste.
  • Fiddle with the post settings slightly.
  • Post.

Just one extra step, and that step consists of hitting Command-Space, typing blog, and hitting return. Given how easy that is, I’m quite happy with it. Particularly since some of my custom directives make certain kinds of content easier, and because reStructuredText is better to compose in than psuedo-HTML.

In fact, when I first wrote about reStructuredText, I complained about the hyperlink format, but having written a blog post or two with it, I find that I actually prefer it. It makes it easier to highlight the links and then go get the actual URLs later, if that’s what I want to do, and if not the short link syntax is actually fine.

Getting to that workflow turned out to be fairly tricky. I’m sure that I could have approached it in ways that would have made things easier. The critical components are:

This is what happens, thanks to a combination of those components, when I invoke the shell script with Quicksilver, after I’ve copied the text in jEdit:

  • The shell script pastes the contents of the clipboard to the pre-processor, which strips out some things, like metadata that I have in the file but don’t want in the post, and puts the newly-cleaned content into the clipboard
  • The shell script pastes the clipboard to rst2wp, which then puts its output to the clipboard.
  • The shell script pastes the clipboard to the post-processor, which does some minor rearranging to suit my particular workflow.

All of which saves what would be quite a lot of time if I had to do the cleanup by hand.

One of the major obstacles I encountered was, of course, character encoding. I’ll probably write that up later this week, because the solutions are poorly doumented, and it’s not a fun thing to bang your head against.

At some point I might try to clean the scripts up and to make the effort to post to WordPress directly. I think the best way for that to work would be to submit the post as a draft, get the id of the draft, and then open a browser window with that draft open for editing. That would save at least a moment or two… the tricky part, it appears, is getting the tags to submit properly.

I do have some issues with reStructuredText, but need to put a little more thought into how I think they should be fixed before posting about them. I’m primarily unhappy with how custom directives are handled.

All in all, very much a developer’s endeavor: lots of effort to make something seem almost exactly the same for benefits that most people wouldn’t notice or might think of as disadvantages.

This entry was posted on Tuesday, July 14th, 2009 at 22:57 14 Jul 2009 and is filed under Blog. You can follow any responses to this entry through the RSS 2.0 feed. You can skip to the end and leave a response. Pinging is currently not allowed.

4 Responses to “Blog Workflow with reStructuredText”

  1. matt Says:
    02 Aug 2009 at 00:43

    I’m glad you find my rst2wp script useful! I just stumbled upon your post and didn’t know someone else used it. I uploaded a new version BTW, that supports literal blocks (useful for displaying code) and no longer adds CSS classes to links.

    Regarding the character encoding troubles: You could have just asked me :)

  2. Tadhg Says:
    03 Aug 2009 at 21:44

    Matt: It’s definitely useful! Yes, I should have thought of emailing you to see if you had tips, but that’s not what tends to spring to mind when you’re in the middle of wrestling with code…

    Heh, that’s funny, I hacked in literal block support and was thinking I should pass it along to you—I’ll check out your new version.

    Incidentally, I have a better pipeline now, one that doesn’t use the clipboard: http://tadhg.com/wp/2009/07/28/better-rest-wordpress-pipeline/

    Thanks for the update!

  3. workflow junky Says:
    26 Aug 2009 at 11:02

    I always use notepad for my posts. I’ve tried jEdit and others, but I found that keeping it simple works the best with me. On your advice I am now checking out reStructedText.

  4. Greg Thornton Says:
    17 Jan 2010 at 16:47

    I too had a copy/paste workflow with reSt and WordPress. It annoyed me enough (and subsequently made me post infrequently enough) to force me to create a nice WordPress reSt editor plugin: http://xdissent.com/projects/wordprest/

    Now you can store your reSt source right along with the post content, generate HTML, configure rst2html.py options, and more from within your WordPress admin. Hope it helps!

Leave a Reply