Asciidoctor — Fast AsciiDoc Processor and Publishing Toolchain

Introduction

Asciidoctor is an open-source text processor that converts AsciiDoc markup into HTML5, DocBook 5, PDF, and other publishing formats. Written in Ruby, it provides a faster and more feature-rich alternative to the original AsciiDoc Python implementation, and has become the standard toolchain for technical documentation, books, and API references in the AsciiDoc ecosystem.

What Asciidoctor Does

• Parses AsciiDoc source files into a document model and renders them to multiple output formats
• Produces semantic HTML5 with built-in styling and syntax highlighting
• Generates PDF documents through the asciidoctor-pdf extension
• Supports DocBook 5 output for integration with XML-based publishing pipelines
• Provides an extensible architecture for custom converters, preprocessors, and macros

Architecture Overview

Asciidoctor is a Ruby library with a CLI wrapper. It processes AsciiDoc input in two phases: parsing (building an abstract syntax tree from the markup) and conversion (rendering the AST into the target format). The converter is pluggable — the core ships HTML5 and DocBook converters, while extensions like asciidoctor-pdf and asciidoctor-epub3 provide additional output formats. The extension API allows custom blocks, macros, and tree processors.

Self-Hosting & Configuration

• Install via gem install asciidoctor on any system with Ruby 2.7+
• Also available as a Docker image, Homebrew formula, and Linux distribution package
• Configure document attributes (author, version, TOC, theme) in the document header or via CLI flags
• Use asciidoctor-pdf for PDF generation and asciidoctor-diagram for diagram rendering
• Integrate into build pipelines with Gradle (asciidoctor-gradle-plugin) or Maven plugins

Key Features

• Processes AsciiDoc documents 100x faster than the legacy Python implementation
• Rich syntax support including tables, admonitions, cross-references, and conditional includes
• Built-in syntax highlighting for code blocks via Rouge, Pygments, or highlight.js
• Extensible with a well-documented Ruby API for custom processing
• Active ecosystem with PDF, EPUB, reveal.js, and diagram extensions

Comparison with Similar Tools

• Markdown / CommonMark — simpler syntax with fewer features; AsciiDoc handles complex technical documents better
• Sphinx (reStructuredText) — Python-based doc generator; Asciidoctor offers lighter setup and faster processing
• Pandoc — universal document converter; Asciidoctor provides deeper AsciiDoc support and a richer extension API
• LaTeX — typesetting for academic publishing; Asciidoctor is more accessible for software documentation
• MkDocs — Markdown-based static sites; Asciidoctor supports richer markup for books and specifications

FAQ

Q: Is AsciiDoc the same as Asciidoctor? A: AsciiDoc is the markup language. Asciidoctor is the processor that converts AsciiDoc files to output formats.

Q: Can I use Asciidoctor without Ruby? A: Yes. AsciidoctorJ runs on the JVM, and Asciidoctor.js runs in Node.js and browsers. Both are official ports.

Q: Does it work with GitHub? A: Yes. GitHub natively renders .adoc files in repositories using Asciidoctor.

Q: How does it compare to Markdown for documentation? A: AsciiDoc supports tables, admonitions, includes, cross-references, and conditional content natively — features that require nonstandard extensions in Markdown.

Sources

• https://github.com/asciidoctor/asciidoctor
• https://docs.asciidoctor.org/