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.

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
10/9/13: Java integration and Maven/Gradle plugins already exist,
though improvements are on the way].

comments powered by Disqus