This is the documentation for the Ruby-based AsciiDoc processor, Asciidoctor. Asciidoctor currently serves as the reference implementation for how to interpret the AsciiDoc language. If you’re looking for the documentation for the AsciiDoc language, see the AsciiDoc section of this website.
Asciidoctor is a fast, open source, Ruby-based text processor for parsing AsciiDoc into a document model and converting it to output formats such as HTML 5, DocBook 5, manual pages, PDF, and EPUB 3. This Ruby library is often referred to as Asciidoctor core. That’s because Asciidoctor is also the name of the family of projects that contribute extensions and tools for processing AsciiDoc. When we say Asciidoctor in this section of the documentation, we’re specifically referring to Asciidoctor core.
To simplify installation, Asciidoctor is packaged and distributed to RubyGems.org as a RubyGem named asciidoctor. The asciidoctor gem can be installed on all major operating systems using Ruby packaging tools (gem or bundle). Asciidoctor is also distributed as a package for numerous Linux distributions as well as macOS.
Asciidoctor is open source software available under the terms of the MIT license and hosted on GitHub.
Asciidoctor is the successor to AsciiDoc.py (aka AsciiDoc Python). If you’re using AsciiDoc.py, follow Migrate from AsciiDoc.py to learn how to upgrade to Asciidoctor.
Asciidoctor provides two primary interfaces for processing AsciiDoc documents:
$ asciidoctor document.adoc
See Process AsciiDoc Using the CLI to learn more about this interface.
See Process AsciiDoc Using the API to learn more about this interface.
AsciiDoc is the language.
Asciidoctor is the processor.
You compose documents using the AsciiDoc language, which is a text-based writing format. The AsciiDoc language was designed to be unobtrusive and concise to simplify writing and make it more pleasant. But AsciiDoc itself is not a publishing format. It’s more like a shorthand. That’s where an AsciiDoc processor comes in.
An AsciiDoc processor, such as Asciidoctor, reads the AsciiDoc source and converts it to publishable formats such as HTML 5 or PDF. It can also convert it to formats which themselves can be processed by a publishing toolchain, such as DocBook.
Since AsciiDoc is not published as is, the processing step provides an opportunity to augment the document by expanding shorthand codes, layering in integrations, and applying a pleasant visual style. That augmentation is a large part of what Asciidoctor does.
In brief, you give AsciiDoc source to Asciidoctor and it gives you a result you can publish.
When we talk about Asciidoctor in this section, we are talking about the core processor and built-in converters. Asciidoctor also has an ecosystem of extensions, converters, build plugins, and tools to help you author and publish AsciiDoc. You can find the documentation for these projects elsewhere on this site or in the Asciidoctor organization on GitHub.
Thanks to AsciidoctorJ, Asciidoctor can be used in any program that runs on a Java Virtual Machine (JVM). Under the covers, AsciidoctorJ uses JRuby to run Asciidoctor, but this is hidden behind a Java API. AsciidoctorJ even provides an alternate CLI, which means you can get the full Asciidoctor experience with only a Java runtime. Building atop AsciidoctorJ, there are also plugins that integrate Asciidoctor into Apache Maven, Gradle, or Javadoc builds.