Asciidoctor is a fast text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook 5 or 4.5, EPUB3, PDF and other formats. Asciidoctor is the leading implementation of the AsciiDoc syntax, first introduced and implemented in the Python-based AsciiDoc project.
Asciidoctor is written in Ruby and can be used on any Ruby runtime, including JRuby. It can also be run on the JVM via AsciidoctorJ, a formal Java API which leverages JRuby underneath, or run in JavaScript using Asciidoctor.js, a transcompiled version of the Ruby codebase.
Asciidoctor is open source, made available under the MIT license. The Asciidoctor RubyGem is published to rubygems.org and can also be installed on several popular Linux distributions using one of the provided packages. The git repositories for the project are hosted under the Asciidoctor organization on GitHub to encourage the widest participation.
While Asciidoctor aims to offer full compliance with the AsciiDoc syntax implemented by AsciiDoc Python (with some exceptions), it’s far more than just a clone of AsciiDoc Python.
What’s unique about the Asciidoctor implementation?
Asciidoctor renders AsciiDoc source files and strings to HTML 5, DocBook 4.5 and other formats, including HTML 5 presentations (deck.js, dzslides).
What follows are highlights of its most notable features.
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 (among the most popular gems in the Ruby ecosystem).
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 50 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. Plugins are available for Apache Maven, Gradle, and Rewrite. These plugins are based on the Java integration library for Asciidoctor.
Asciidoctor also ships with a command-line interface (cli).
The Asciidoctor cli, asciidoctor, is a drop-in replacement for the asciidoc.py script from the AsciiDoc Python distribution.