AsciiDoc is a lightweight markup language akin to Markdown. Going beyond Markdown, AsciiDoc supports all the structural elements necessary for drafting articles, technical manuals and books. Several O’Reilly authors, including Matthew McCullough, Tim Berglund and Matt Neuburg, have used it to write books for that iconic technical library. AsciiDoc is fully capable of serving as a shorthand replacement for DocBook, which it can also output.

One way to think of the relationship between AsciiDoc and DocBook is that AsciiDoc is to DocBook as RelaxNG Compact is to XML Schema. With AsciiDoc, you drop the angled-brackets (i.e., XML), but not the semantics.

Here’s an example of a document written in AsciiDoc, shown above the output it produces:

(You don’t want to see how the DocBook looks for this example. Let’s just say, there isn’t enough room on the screen to show it to you.)

The AsciiDoc project, written in Python, was the only implementation of the AsciiDoc syntax…​until the arrival of "the doctor".

Asciidoctor is the first project to implement the AsciiDoc syntax in another language, in this case Ruby. It’s an open source library (MIT licensed) published as a RubyGem to rubygems.org. The project recently moved to the Asciidoctor organization on GitHub to sustain its rapid growth.

While Asciidoctor aims to offer full compliance with the AsciiDoc syntax (with some exceptions, noted in the project README), it’s more than just a clone.

Asciidoctor uses a set of built-in ERB templates to generate HTML 5 and DocBook 4.5 output that is structurally equivalent to what AsciiDoc produces. Any of these templates can be replaced by a custom template written in any template language available in the Ruby ecosystem. Custom template rendering is handled by the Tilt template abstraction library, a project created by another GitHubber, Ryan Tomayko.

Leveraging the Ruby stack isn’t the only benefit of Asciidoctor. Unlike the AsciiDoc Python implementation, Asciidoctor parses and renders the source document in discrete steps. This makes rendering the document optional and gives Ruby programs the opportunity to extract, add or replace information in the document by interacting with the document object model Asciidoctor assembles. Developers can use the full power of the Ruby programming language to play with the content in the document.

No coverage of Asciidoctor would be complete without mention of its speed. Despite not being an original goal of the project, Asciidoctor has proven startlingly fast. It loads, parses and renders documents at least 25 times as fast as the Python implementation. That’s good news for developer productivity and good news for GitHub or any server-side application that needs to render AsciiDoc markup. Asciidoctor also offers several levels of security, further justifying its suitability for server-side deployments.

Asciidoctor’s usage is not limited to the Ruby community. Thanks to JRuby, a port of Ruby to the JVM, Asciidoctor can be used inside Java applications as well (and eventually in Java build tools like Apache Maven). Asciidoctor also ships with a command-line interface (cli), written by Red Hat’s Jason Porter. The Asciidoctor cli, asciidoctor, is a drop-in replacement for the asciidoc.py script from the AsciiDoc Python distribution.

The future is bright for AsciiDoc. Despite being a seasoned, 10-year-old markup language, adoption of AsciiDoc has never been stronger. The developers have lots of ideas about how to improve and extend Asciidoctor, some of which push beyond the AsciiDoc syntax.

Write docs with pleasure!