Asciidoctor

Asciidoctor is an open-source processor and publishing toolkit for turning AsciiDoc into documentation and other formats. It is a strong fit for writers and development teams who want publishing to work across Ruby, JVM, or JavaScript environments. Its breadth is valuable, but PDF and EPUB output require separate converters, and its safety modes are not a substitute for output sanitization.

Overview

Asciidoctor accepts AsciiDoc files and strings through a command-line interface or Ruby API. The core converts to HTML5, DocBook 5, and man pages; PDF and EPUB 3 conversion come from separate gems. That core is enough for web documentation and reference material, while teams publishing books or PDFs must add components to their toolchain.

Distribution options include a RubyGem, Docker image, packages for numerous Linux distributions, and macOS packages through Homebrew and MacPorts. The MIT license and CI/CD integration make Asciidoctor practical for automated publishing pipelines. Community chat, documentation, GitHub repositories, and issue trackers provide support avenues.

Key features

Formats and presentation

The default HTML experience includes a stylesheet and integrations for Font Awesome, highlight.js, Rouge, Pygments, and MathJax. Those options serve documentation that needs icons, code highlighting, or mathematical notation without changing the underlying AsciiDoc workflow. The separate PDF and EPUB gems are the main trade-off for publishers who need those outputs.

Runtimes and integrations

Asciidoctor runs on Ruby, on the JVM through AsciidoctorJ, and in JavaScript environments through Asciidoctor.js. Maven and Gradle plugins, Javadoc integration, browser preview extensions, an IntelliJ plugin, and tools such as Asciidoctor Diagram connect it to common authoring and build workflows. This range makes it easier to fit into an existing development stack, though teams should choose the runtime and integrations that match their own environment.

Ruby implementations documented for the project include CRuby 2.3–3.3, JRuby 9.1–9.4, and TruffleRuby (GraalVM). The command-line interface and Ruby API offer distinct ways to process documents; the available security defaults differ, so deployment context matters.

Security modes

Asciidoctor provides UNSAFE, SAFE, SERVER, and SECURE modes. The API defaults to SECURE, while the CLI defaults to UNSAFE. Crucially, safe modes do not sanitize generated output and are not a comprehensive security framework. That distinction matters when processing untrusted documents or publishing generated content: mode selection alone does not establish a secure output pipeline.

Pricing

Asciidoctor costs nothing. The free plan is the MIT-licensed open-source toolchain, with core HTML5, DocBook 5, and man-page converters. It suits individuals and teams who can use the core formats and manage their own publishing setup. PDF and EPUB 3 require separate gems, so the free core does not deliver those formats through built-in converters. There is no free trial because the software is free.

Platforms

Asciidoctor works on Linux, macOS, and Windows, and is also available through web and self-hosted environments, APIs, and extensions. Ruby, JVM, and JavaScript runtime options give teams flexibility across language ecosystems. Its distribution as a Docker image, RubyGem, Linux packages, and macOS packages offers several deployment routes, but the supported Ruby implementation ranges are relevant when selecting a Ruby-based setup.

Who it's for

Asciidoctor is best for technical writers and development teams already producing AsciiDoc or looking to automate documentation across multiple runtimes. It is particularly well suited to teams whose needs center on HTML, DocBook, or man pages and who want build-system integrations. It is less compelling for publishers who want PDF and EPUB conversion built into one core install, or for anyone who needs safe modes to sanitize generated output.

Pros and cons

Broad runtime choice: Ruby, JVM, and JavaScript support lets teams align document processing with different application stacks.

Useful core formats: Built-in HTML5, DocBook 5, and man-page converters cover web documentation and reference publishing without extra format converters.

Workflow integrations: Maven, Gradle, Javadoc, editor, and browser integrations can fit AsciiDoc into authoring and build processes.

Separate book-format converters: PDF and EPUB 3 depend on separate gems, adding setup for teams that need those outputs.

Security caveat: The CLI defaults to UNSAFE, and safe modes do not sanitize output, so secure publishing requires more than selecting a mode.

Alternatives

For API documentation, Scalar is a freemium option with a free plan capped at three APIs, one SDK of up to 25 endpoints, one editor seat, and 50 Agent Scalar credits; it is a better fit when those API-specific limits suit the project. Sphinx is a free, BSD 2-Clause-licensed option that can be installed locally or self-hosted, and is worth considering for teams seeking that alternative. For a broader browse, see Documentation Generators.

Swift Package Manager, Kotlin/JS, Natural Docs, StepShot, Swagger Codegen, and Dart pub are also alternatives.

Verdict

Choose Asciidoctor if you want an open-source AsciiDoc publishing pipeline that can plug into Ruby, JVM, or JavaScript workflows and whose core formats meet your needs. Its runtime and build integration breadth is the strongest reason to adopt it; look elsewhere if you want PDF and EPUB converters bundled into the core or need built-in output sanitization.