The doctor will see you now

AsciiDoc replacement gets further fixes

Elliot Bentley

GitHub and Red Hat collaboration Asciidoctor adds more handy new macros and extension system prototype.

An update to a new, Ruby-based interpreter for the AsciiDoc file format was pushed out yesterday, bringing handy new macros and extra speed, as well as fixing some common annoyances.

Asciidoctor was launched by GitHub’s Ryan Waldron and Red Hat’s Dan Allen in January as an alternative implementation of AsciiDoc, with the aim of fixing some the standard interpreter’s long-standing problems.

Nine months on from a 0.1.0 release, Asciidoctor has been downloaded 50,000 times and a number of open source projects have made the shift to using this software, including Groovy, Spring XD and Neo4j. Development has continued since, and yesterday the fifth version of Asciidoctor was pushed to RubyGems, bringing with it an array of further improvements.

“Asciidoctor 0.1.4 was originally planned to be a small release,” wrote Dan Allen and Sarah White on the project’s blog. “Instead, it turned out to be a summer-long project.”

Originally created as a preprocessor to the complex DocBook markup language, Asciidoc files can now be exported to a range of formats, from HTML to PDF to ePub. Similar to Markdown in syntax, it can be – and frequently is – used to produce entire technical manuals.

However, the standard interpreter, written in Python in 2002, has remained the only conversion option for a decade. Asciidoctor is a fresh take written in Ruby (GitHubbers’ language of choice), introducing custom HTML templates, a flexible document object model, and a 25x speed increase. It’s now used to render every AsciiDoc file on GitHub.

Version 0.1.4 of AsciiDoc, rolled out this week, increases speed by an extra 15% and adds further improvements – none revolutionary, but all likely to be welcomed by frequent users of the format.

New macros allow for embedding Font Awesome icons and videos hosted on YouTube and Vimeo, document sections can be inserted directly from an external URL using the ‘include’ tag and image positioning attributes can be specified using macros.

The release also fixes some of AsciiDoc’s most annoying habits: lines are no longer dropped when references are missing, callout numbers in code are no longer selectable and users can toggle between wrapped and scrolling HTML.

The most exciting inclusion though is a prototype of Asciidoctor’s extension system. While AsciiDoc includes similar functionality in the way of ‘filters’, Asciidoctor’s extensions are promised to be easier to build and distribute.

A comprehensive changelist of new features is available at the Asciidoctor blog, and the Gem package is on RubyGems now. Yet to come – though not necessarily in the next Asciidoctor release – is Java integration, a Maven plugin and a Gradle plugin [Update 10/9/13: Java integration and Maven/Gradle plugins already exist, though improvements are on the way].

Inline Feedbacks
View all comments