Asciidoctor Documentation

Asciidoctor is a fast text processor and publishing toolchain for converting AsciiDoc content to HTML, DocBook, and other formats. Asciidoctor is packaged as a RubyGem and published to The gem is also included in several Linux distributions, including Fedora, Debian, Ubuntu, and Alpine. Asciidoctor is open source, hosted on GitHub and released under the MIT license.

The Big Picture

Asciidoctor reads content written in plain text, as shown in the panel on the left in the image below, and converts it to HTML5, as shown rendered in the right panel. Asciidoctor adds a default stylesheet to the HTML5 document, as shown, to provide a pleasant out-of-the-box experience.

AsciiDoc Syntax Processing

Asciidoctor reads and parses text written in the AsciiDoc syntax, then feeds the parse tree into a set of built-in templates to produce HTML, PDF, DocBook, man page, and other output formats. You have the option of writing your own converter or loading Tilt-supported templates to customize the generated output or produce alternative formats. Asciidoctor also offers a responsive theme based on Foundation to style the HTML5 output.

The JVM and JavaScript

You can run Asciidoctor on the JVM using JRuby. To invoke the Asciidoctor API directly from Java and other JVM languages, use AsciidoctorJ. There are plugins available that integrate Asciidoctor into Apache Maven, Gradle, or Javadoc builds.

Asciidoctor also runs in JavaScript. We use Opal to transcompile the Ruby source to JavaScript to produce Asciidoctor.js, a fully-functional version of Asciidoctor that works in any JavaScript environment, such as a web browser or Node.js. Asciidoctor.js is used to power the AsciiDoc preview extensions for Chrome, Atom, Brackets and other web-based tooling.