Asciidoctor

Asciidoctor is an open-source text processor and publishing toolchain for turning AsciiDoc files or strings into HTML5, DocBook, manual pages, and other formats. The core includes converters for HTML5, DocBook 5, and man pages; PDF and EPUB 3 conversion is available through separate gems. Documents can be processed through a command-line interface or Ruby API, with runtimes for Ruby, the JVM through AsciidoctorJ, and JavaScript through Asciidoctor.js. It works on Linux, macOS, and Windows, and is distributed as a RubyGem, Docker image, Linux packages, and macOS package. Its ecosystem includes Maven and Gradle plugins, editor and browser extensions, and diagram tools. Default HTML output includes a stylesheet and integrations such as Font Awesome, highlight.js, Rouge, Pygments, and MathJax. Asciidoctor is free under the MIT License. Its API defaults to SECURE mode, while the CLI defaults to UNSAFE; the project cautions that safe modes do not sanitize generated output or provide a complete security framework.

Asciidoctor offers multiple ways to process and publish AsciiDoc, with built-in core converters and a broad ecosystem of integrations. Users handling untrusted content should note its security-mode limitations and the CLI's UNSAFE default.

Asciidoctor suits people writing and publishing in AsciiDoc who need document conversion across platforms or runtimes. Build and editor integrations may also suit teams using Maven, Gradle, or compatible editors.

Asciidoctor is an open-source processor for turning AsciiDoc into documentation and publication formats. It is best for writers and development teams who want AsciiDoc to work across Ruby, JVM, or JavaScript projects. Its format and integration range makes it a capable publishing foundation, though PDF and EPUB conversion require separate components.

Overview

Asciidoctor accepts AsciiDoc files and strings through a command-line interface or Ruby API. The core processor converts them to HTML5, DocBook 5, and man pages; PDF and EPUB 3 output comes from separate gems. That core set covers web documentation and reference material, while teams publishing books or PDFs need to add converters to their setup.

Distribution options include a RubyGem, Docker image, packages for numerous Linux distributions, and a macOS package through Homebrew and MacPorts. The MIT license and CI/CD integration suit teams incorporating document generation into software workflows. Community chat, documentation, GitHub source repositories, and issue trackers provide support channels.

Key features

Output and presentation

Default HTML output includes a stylesheet and integrations for Font Awesome, highlight.js, Rouge, Pygments, and MathJax. These options support styled documentation with icons, code highlighting, and mathematical content. The core converter set is focused, but the separate PDF and EPUB gems add a dependency step for those formats.

Runtimes and integrations

Asciidoctor runs on Ruby, on the JVM through AsciidoctorJ, and in JavaScript environments through Asciidoctor.js. Maven and Gradle plugins connect it to build pipelines, with Javadoc integration also available. Browser preview extensions powered by Asciidoctor.js and an IntelliJ plugin extend it into writing and editing workflows; Asciidoctor Diagram adds another tool in the ecosystem. This breadth helps teams use AsciiDoc across different stacks, though choosing and maintaining the right runtime and plugins is part of the setup.

Processing and security

The Ruby API defaults to SECURE mode, while the command-line interface defaults to UNSAFE. Asciidoctor also offers SAFE and SERVER modes, but its safe modes do not sanitize generated output and are not a comprehensive security framework. That distinction matters when processing untrusted content: users should not treat a safe mode alone as protection for rendered output, and CLI users need to pay particular attention to the default.

Pricing

Asciidoctor costs free. The free plan is open-source software under the MIT license, with core HTML5, DocBook 5, and man page converters. It has no stated seat or usage quota, but PDF and EPUB 3 require separate gems. There is no free trial because the software is free.

Platforms

Asciidoctor works on Linux, macOS, and Windows, with API, extension, web, and self-hosted options. Ruby implementations documented for use include CRuby 2.3–3.3, JRuby 9.1–9.4, and TruffleRuby (GraalVM). The JVM and JavaScript runtime options broaden its reach beyond Ruby-based projects.

Who it's for

Asciidoctor is a strong fit for documentation teams and technical writers already using AsciiDoc, particularly when they want to integrate publishing into a Ruby, JVM, or JavaScript workflow. Its build plugins and CI/CD support are useful for automated documentation pipelines. It is less compelling for a reader who needs PDF or EPUB output without installing additional converters, or who expects safe modes to provide complete protection for untrusted content.

Pros and cons

• Pro: Core converters cover HTML5, DocBook 5, and man pages, with PDF and EPUB 3 available through separate gems.
• Pro: Ruby, JVM, and JavaScript runtimes plus Maven and Gradle plugins suit varied development environments.
• Pro: MIT-licensed and free, with multiple distribution options and CI/CD integration.
• Con: PDF and EPUB publishing requires additional gems rather than built-in converters.
• Con: Safe modes do not sanitize output or serve as a complete security framework, and the CLI defaults to UNSAFE.

Alternatives

For a broader directory of tools in this category, browse Documentation Generators.

• Scalar is worth considering for API documentation: 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 costs $150 a month, billed $125/.
• Sphinx is another free, BSD 2-Clause-licensed open-source 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.
• mdBook is a free, open-source option under the MPL-2.0 license for Linux, macOS, and Windows.
• DocFX is a free open-source static site generator for users working with the .NET SDK 8.0 or higher.
• Doxygen is free, open-source software under the GNU General Public License, with Windows, Linux, and macOS downloads.
• Stoplight Elements offers free, open-source API documentation building blocks that can be embedded into an existing CMS.
• Widdershins is free, open-source MIT-licensed software available through npm or a repository clone.

Verdict

Choose Asciidoctor if you want a free, MIT-licensed AsciiDoc toolchain that can fit Ruby, JVM, or JavaScript workflows and connect to build pipelines. Its main advantage is that range of runtimes and integrations; look elsewhere if you need PDF or EPUB converters built into the core or require a comprehensive security framework for untrusted content.