Asciidoctor

Asciidoctor is an open-source processor and publishing toolchain for turning AsciiDoc into documentation and publication formats. It is best suited to writers and development teams that want AsciiDoc to fit Ruby, JVM, or JavaScript workflows. Its range of runtimes and converters is compelling, but PDF and EPUB publishing requires separate components.

Overview

Asciidoctor accepts AsciiDoc files and strings through a command-line interface or Ruby API. Its core converts documents to HTML5, DocBook 5, and man pages; PDF and EPUB 3 conversion come from separate gems. That makes it a flexible foundation for documentation pipelines, while adding a setup step for teams that publish books or need those formats.

Distribution options include a RubyGem, Docker image, packages for numerous Linux distributions, and macOS packages through Homebrew and MacPorts. The MIT license permits use as open-source software, and CI/CD integration makes it a fit for automated publishing workflows. Community chat, documentation, GitHub repositories, and issue trackers are project support resources.

Key features

Formats and presentation

The default HTML output includes a stylesheet and integrations for Font Awesome, highlight.js, Rouge, Pygments, and MathJax. These give teams options for icons, code highlighting, and mathematical content in their rendered documentation. The core converter set is useful for web and reference publishing, but PDF and EPUB 3 are not part of that built-in set.

Runtimes and integrations

Asciidoctor runs on Ruby, through AsciidoctorJ on the JVM, and through Asciidoctor.js in JavaScript environments. Maven and Gradle plugins connect it to common build workflows, with Javadoc integration also supported. Browser preview extensions powered by Asciidoctor.js cover Chrome, Atom, Brackets, and other web-based tools; an IntelliJ plugin and Asciidoctor Diagram extend the wider ecosystem. This breadth helps teams incorporate AsciiDoc into existing environments rather than adopt a single prescribed editor or runtime.

Security and requirements

Security modes include UNSAFE, SAFE, SERVER, and SECURE. SECURE is the Ruby API default, while the command-line interface defaults to UNSAFE. Safe modes do not sanitize generated output and are not a comprehensive security framework, so generated content should not be treated as safe for untrusted input merely because a safe mode is enabled.

Documented Ruby implementations are CRuby 2.3–3.3, JRuby 9.1–9.4, and TruffleRuby (GraalVM). Asciidoctor also works on Linux, macOS, and Windows, and its runtime options add JVM and JavaScript environments for teams working outside a Ruby-only setup.

Pricing

Asciidoctor is free: its plan costs nothing and is open source under the MIT License. The plan includes the core HTML5, DocBook 5, and man page converters. There is no free trial because the software is free to use. Teams needing PDF or EPUB 3 conversion must add the separate gems; the core plan itself does not include those converters.

Platforms

Asciidoctor supports Linux, macOS, and Windows, with distribution options including Linux packages and macOS package managers. It is also available as a Docker image and offers API, web, extension, and self-hosted contexts. Ruby, JVM, and JavaScript runtime choices give developers several ways to connect it to their toolchains.

Who it's for

Asciidoctor suits technical writers and development teams standardizing on AsciiDoc who need multiple output formats, build integration, or flexibility across Ruby, JVM, and JavaScript. It is a particularly strong fit for automated documentation pipelines and teams that can manage converter dependencies. Readers looking for PDF or EPUB conversion bundled into the core, or a security boundary for processing untrusted content, should consider those limitations before choosing it.

Pros and cons

Pros

• Multiple runtimes: Ruby, JVM, and JavaScript options let teams match Asciidoctor to different development environments.
• Useful built-in output: HTML5, DocBook 5, and man page converters cover web documentation and reference publishing without separate format gems.
• Build and editor ecosystem: Maven, Gradle, Javadoc, browser previews, and an IntelliJ plugin make it easier to integrate AsciiDoc into existing workflows.
• Free under MIT: The open-source license and zero-cost plan make it accessible for individual and team use.

Cons

• Extra converters for books: PDF and EPUB 3 require separate gems, adding setup beyond the core processor.
• Safe modes have limits: They do not sanitize output or provide a comprehensive security framework.
• CLI default is UNSAFE: Teams processing untrusted input need to account for that default and the limits of safe modes.

Alternatives

Compare documentation generators if you want to consider a broader set of tools.

Scalar is worth considering when API documentation is the priority: its free plan includes up to 3 APIs, 1 SDK with up to 25 endpoints, 1 editor seat, and 50 Agent Scalar credits. Its Pro plan is $150 a month, billed $125/.

Sphinx is a free, BSD 2-Clause-licensed option that can be installed locally or self-hosted. Kotlin/JS is a free Kotlin compiler target for JavaScript configured with the Kotlin Multiplatform Gradle plugin, making it the relevant alternative when that is the target workflow.

mdBook is a free, open-source option under MPL-2.0 for readers considering another documentation tool. DocFX is a free open-source static site generator for teams with .NET SDK 8.0 or higher. Doxygen is a free, GPL-licensed option with Windows, Linux, and macOS downloads.

MkDocs and Stoplight Elements are also alternatives to consider.

Verdict

Choose Asciidoctor if you want a free, MIT-licensed AsciiDoc publishing toolchain that can span Ruby, JVM, and JavaScript and connect to established build workflows. Its strongest case is that breadth paired with capable core converters. Look elsewhere if bundled PDF or EPUB conversion is essential, or if you need safe modes to serve as a complete security framework.