»

Blogging with AsciiDoc


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 WordPress.com. 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 <br /> 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 wordpress.com 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:

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

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

$ blogpost.py update 38 doc/blogging_with_asciidoc.txt
updating published post 'Blogging with AsciiDoc'...
id: 38
url: https://srackham.wordpress.com/2008/05/38/blogging-with-asciidoc/

$ blogpost.py 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.

This entry was posted on May 15, 2008 at 2:33 am and is filed under AsciiDoc, blogpost, Weblog client, WordPress. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

5 Responses to “Blogging with AsciiDoc”

  1. Posting from the command line with Blogpost « Minimalistic life in text-mode Says:
    August 17, 2008 at 6:10 pm | Reply

    […] Blogpost’s(currently version 0.9.1) creator, Stuart Rackham is also the guy who wrote AsciiDoc. After deciding on wordpress.com as his online notes keeping platform, he found a few rendering problems when cutting and pasting his AsciiDoc formatted notes onto WordPress.com’s blogging interface. You can read about it from here: Stuart’s Notes. […]

  2. Drew Says:
    November 27, 2008 at 1:52 am | Reply

    This is working really well for me, but I am having some trouble with time zone… Specifically when I make a post this way, it gets set to 9 hours ahead of the current time (my server is 9 hours ahead of GMT, so the end result is that the post gets set to 18 hours ahead of GMT).

    Has anyone else had/solved similar issues?

  3. textonly Says:
    January 9, 2011 at 7:47 pm | Reply

    Thanks for blogpost !

    I was looking for a command-line tool to be able to run some of the PHP in a WordPress site before encapsulating it into a plugin – this looks like just what I need to get started.

    I found a minor issue:
    When I try to list the site’s current posts (I’m not the author), several of them have unicode characters in them that cause:

    File “blogpost.py”, line 826, in
    blog.list()
    File “blogpost.py”, line 463, in list
    print ‘title: %s’ % post.title
    UnicodeEncodeError: ‘ascii’ codec can’t encode character u’\u2018′ in position 27: ordinal not in range(128)

  4. Sigfried Steven Gold Says:
    December 12, 2011 at 12:49 pm | Reply

    I sure would like to be using blogpost, but no luck. Parsing errors.

    Got this at first:

    (p27)sigfried@ubuntu:~/software/blogpost$ ~/software/blogpost/blogpost.py -d html –title=’This is from blogpost’ post ~/macdrive/personal/junk/junk.html > junk.html
    Traceback (most recent call last):
    File “/home/sigfried/software/blogpost/blogpost.py”, line 846, in
    blog.create()
    File “/home/sigfried/software/blogpost/blogpost.py”, line 495, in create
    self.post()
    File “/home/sigfried/software/blogpost/blogpost.py”, line 559, in post
    self.id = self.server.newPost(post, self.is_published())
    File “/home/sigfried/software/blogpost/wordpresslib.py”, line 265, in newPost
    idNewPost = int(self._server.metaWeblog.newPost(self.blogId, self.user, self.password, blogContent, 0))
    File “/usr/lib/python2.7/xmlrpclib.py”, line 1226, in __call__
    return self.__send(self.__name, args)
    File “/usr/lib/python2.7/xmlrpclib.py”, line 1577, in __request
    verbose=self.__verbose
    File “/usr/lib/python2.7/xmlrpclib.py”, line 1266, in request
    return self.single_request(host, handler, request_body, verbose)
    File “/usr/lib/python2.7/xmlrpclib.py”, line 1299, in single_request
    return self.parse_response(response)
    File “/usr/lib/python2.7/xmlrpclib.py”, line 1469, in parse_response
    p.feed(data)
    File “/usr/lib/python2.7/xmlrpclib.py”, line 559, in feed
    self._parser.Parse(data, 0)
    xml.parsers.expat.ExpatError: undefined entity: line 10, column 0

    I thought it had to do with the HTML document I was trying to post, but figured out it was actually a problem with parsing the existing WordPress stuff — which was a brand new install with no customization. I narrowed it down to these lines:

    and specifically to the » entities. When I got rid of those by hacking up my WordPress installation a little (those are part of the standard header). I got another error:

    (p27)sigfried@ubuntu:~/software/blogpost$ ~/software/blogpost/blogpost.py -d html –title=’This is from blogpost’ post ~/macdrive/personal/junk/junk.html > junk.html
    Traceback (most recent call last):
    File “/home/sigfried/software/blogpost/blogpost.py”, line 846, in
    blog.create()
    File “/home/sigfried/software/blogpost/blogpost.py”, line 495, in create
    self.post()
    File “/home/sigfried/software/blogpost/blogpost.py”, line 559, in post
    self.id = self.server.newPost(post, self.is_published())
    File “/home/sigfried/software/blogpost/wordpresslib.py”, line 265, in newPost
    idNewPost = int(self._server.metaWeblog.newPost(self.blogId, self.user, self.password, blogContent, 0))
    File “/usr/lib/python2.7/xmlrpclib.py”, line 1226, in __call__
    return self.__send(self.__name, args)
    File “/usr/lib/python2.7/xmlrpclib.py”, line 1577, in __request
    verbose=self.__verbose
    File “/usr/lib/python2.7/xmlrpclib.py”, line 1266, in request
    return self.single_request(host, handler, request_body, verbose)
    File “/usr/lib/python2.7/xmlrpclib.py”, line 1299, in single_request
    return self.parse_response(response)
    File “/usr/lib/python2.7/xmlrpclib.py”, line 1475, in parse_response
    return u.close()
    File “/usr/lib/python2.7/xmlrpclib.py”, line 793, in close
    raise ResponseError()
    xmlrpclib.ResponseError: ResponseError()

    I haven’t tracked this one down. I don’t know if the problem is something in my python installation or if Blogpost has aged and no longer works with standard WordPress.

    Let me know if you have advice.

    Thanks,
    Sigfried

  5. srackham Says:
    December 12, 2011 at 6:58 pm | Reply

    It works on wordpress.com. I’m guessing that you have your own WordPress installation so looks like there’s a difference between yours and wordpress.com. The trace seems to indicate problems processing the WordPress RPC response., no idea why though.

    Cheers, Stuart

Leave a comment