Blogging with AsciiDoc

Thu May 15, 2008

Since this blog was written many new features have been added to blogpost – see blogpost media processing

I make lots of notes using AsciiDoc, the sort of stuff that’s to minor and/or not rigorous enough for formal publication, but possibly useful to others.

So I decided it was about time I started posting my notes to a blog. Creating and maintaining posts using the normal browser based interfaces was not an option – just to tedious for words. So I looked around for an HTML friendly blog host that could make a reasonable job of rendering AsciiDoc generated HTML.

After a search (albeit brief) I settled on There is a problem though: Wordpress massages HTML pasted into the Wordpress HTML editor. Here are some rendering problems I observed after pasting AsciiDoc-generated HTML into Wordpress:

  • Paragraph tags are stripped and
    tags inserted at line breaks.
  • Break tags inserted preceeding inline tags.
  • Tables problems because Wordpress seems to insist on the opening table tag occupying a single line.
  • Emoticons are auto-generated.

These problems could be solved by installing the WP Unformatted Wordpress plugin – unfortunately dosn’t allow plugins, in any case blog editing by pasting into the browser is still tedious. Submitting the unmodified HTML via the Wordpress API doesn’t get round these problems either.

My solution was to write blogpost, a Wordpress command-line weblog client for AsciiDoc. blogpost allows you to create, list, delete and update blogs written in AsciiDoc from the command-line. Here are some usage examples:

$ create doc/blogging_with_asciidoc.txt
creating published post 'Blogging with AsciiDoc'...
id: 38

$ list
38: Thu May 15 22:36:47 2008: Blogging with AsciiDoc

$ update 38 doc/blogging_with_asciidoc.txt
updating published post 'Blogging with AsciiDoc'...
id: 38

$ delete 38
deleting post 38...

I have used blogpost to post the AsciiDoc User Guide, a long (around 100 page) and fairly complicated AsciiDoc document.

To get AsciiDoc output into a Wordpress compatible format:

  1. I’ve written an AsciiDoc wordpress.conf configuration file which implements a wordpress backend – all it contains is a few minor adjustments to the existing AsciiDoc html4 backend.
  2. blogpost runs AsciiDoc with the –backend wordpress –no-header-footer options.
  3. blogpost then captures the HTML output from AsciiDoc and removes all extraneous line breaks – the HTML is now Wordpress friendly.

See also:

blogpost uses Michele Ferretti’s Python Wordpress library to communicate with the Wordpress XML-RPC API.

  « Previous: Next: »