Asciidoctor

Asciidoctor is an open-source processor and publishing workbench for people who write in AsciiDoc. It is most compelling for documentation teams that want to connect that format to Ruby, JVM, or JavaScript workflows. Its core handles several practical publishing targets, though print and ebook output takes separate converters.

Overview

Asciidoctor turns AsciiDoc files or strings into published documents through a command-line interface or Ruby API. HTML5, DocBook 5, and man pages are built into the core; PDF and EPUB 3 conversion comes from separate gems. That split suits teams focused on web documentation and reference material, but adds components to manage when books or PDFs are part of the publishing pipeline.

The project is distributed as a RubyGem, Docker image, packages for numerous Linux distributions, and a macOS package through Homebrew and MacPorts. It supports CI/CD integration, making it suitable for automated document builds. Use is under the MIT License, and community chat, documentation, source repositories, and issue trackers are listed as support resources.

Key features

Formats and HTML presentation

The core converters cover web pages, DocBook, and manual pages. Default HTML includes a stylesheet and integrations for Font Awesome, highlight.js, Rouge, Pygments, and MathJax. These give authors options for icons, code highlighting, and mathematical content without changing the source format. The trade-off is that PDF and EPUB 3 are not part of the built-in converter set.

Runtime and build integrations

Asciidoctor runs on Ruby, on the JVM through AsciidoctorJ, and in JavaScript environments through Asciidoctor.js. Maven, Gradle, and Javadoc build plugins help teams incorporate document conversion into software builds; Asciidoctor Diagram is among the ecosystem tools. Browser preview extensions for Chrome, Atom, Brackets, and other web-based tools offer another route to working with AsciiDoc. This breadth matters to organizations with established language and build environments, while it may be more machinery than a writer seeking a standalone editor needs.

Security modes

Asciidoctor provides UNSAFE, SAFE, SERVER, and SECURE modes. The Ruby API defaults to SECURE, while the command-line interface defaults to UNSAFE, so users should not assume identical defaults across entry points. Safe modes do not sanitize generated output and are not a comprehensive security framework. Treating them as complete protection would be a mistake, especially when publishing content from untrusted inputs.

Pricing

Asciidoctor is free: its plan costs nothing and covers open-source use under the MIT License. The included core converters produce HTML 5, DocBook 5, and man pages; PDF and EPUB 3 require separate gems. There is no free trial to evaluate because the software is already free, and no seat or usage caps are given for this plan. It is a straightforward fit for individuals and teams comfortable assembling their own publishing workflow, rather than buyers seeking a priced support or hosted-service tier.

Platforms

Asciidoctor works on Linux, macOS, and Windows. It also spans API, extension, web, and self-hosted contexts, with Ruby, JVM, and JavaScript runtime paths. The documented Ruby implementations are CRuby 2.3–3.3, JRuby 9.1–9.4, and TruffleRuby (GraalVM). Distribution through RubyGems, Docker, Linux packages, Homebrew, and MacPorts gives teams several installation routes, but the Ruby implementation ranges are specific requirements to check against an existing environment.

Who it's for

Asciidoctor is a strong choice for technical writers and development teams already using AsciiDoc who want documents built alongside software or rendered across several runtimes. It is especially useful when HTML, DocBook, and manual pages cover the publishing need. Look elsewhere if your workflow depends on PDF or EPUB output being included in the core, or if you need a security framework that sanitizes generated output.

Pros and cons

• Pros: Core HTML5, DocBook 5, and man page converters cover distinct documentation targets without paid licensing.
• Pros: Ruby, JVM, and JavaScript options, plus Maven and Gradle integrations, make it adaptable to varied build environments.
• Pros: Default HTML includes a stylesheet and integrations for code highlighting, icons, and math rendering.
• Cons: PDF and EPUB 3 need separate gems, adding setup for teams that publish print-ready or ebook formats.
• Cons: CLI defaults to UNSAFE, and safe modes do not sanitize output; careful handling is needed for untrusted content.
• Cons: The Ruby implementation requirements may constrain teams maintaining older or different runtime versions.

Alternatives

Documentation Generators is a useful category starting point for comparing tools by publishing workflow.

Choose Scalar instead when API-focused publishing is the priority: its free plan covers up to 3 APIs, 1 SDK up to 25 endpoints, 1 editor seat, and 50 Agent Scalar credits. Its listed Pro plan is $150 a month, billed $125/.

Kotlin/JS is a free Kotlin compiler target for JavaScript configured with the Kotlin Multiplatform Gradle plugin; consider it when the need is Kotlin-to-JavaScript compilation rather than a general AsciiDoc publishing toolchain.

Sphinx is another free, locally installable or self-hosted open-source option under the BSD 2-Clause license.

DocFX is a free open-source static site generator for teams already able to use the .NET SDK 8.0 or higher.

Doxygen is a free and open-source option with Windows, Linux, and macOS downloads.

mdBook is a free and open-source alternative under the MPL-2.0 license for readers comparing documentation tools.

Stoplight Elements offers open-source API documentation building blocks that can be embedded into an existing CMS.

Dart pub is another free option for readers considering software in this category.

Verdict

Choose Asciidoctor if you want a free, MIT-licensed AsciiDoc processor that can fit Ruby, JVM, or JavaScript pipelines and whose built-in formats meet your needs. Its runtime and build integration range is the main reason to adopt it; the separate PDF and EPUB converters, and the limits of its safe modes, are the main reasons to look elsewhere.