Skip to the content
Know your tech before you buy it. Makers: get listed from $49/mo

Asciidoctor

asciidoctor.org

  • Free plan
  • Windows
  • macOS
  • Linux
  • Web
  • Browser extension
  • API
  • Self-hosted
8.3 Club score Visit asciidoctor.org

What Asciidoctor is

Asciidoctor is an open source text processor and publishing toolchain for turning AsciiDoc files or strings into formats such as HTML5, DocBook, PDF, EPUB 3, and manual pages. Its core provides converters for HTML5, DocBook 5, and man pages; PDF and EPUB 3 conversion comes through separate gems. Users can process documents with a command-line interface or Ruby API. It runs with Ruby, on the JVM through AsciidoctorJ, or in JavaScript environments through Asciidoctor.js, and works on Linux, macOS, and Windows. The ecosystem includes Maven and Gradle plugins, browser extensions, an IntelliJ plugin, and diagram tools. Default HTML output includes a stylesheet and integrations such as Font Awesome, highlight.js, Rouge, Pygments, and MathJax. The project is distributed as a RubyGem, Docker image, Linux packages, and macOS packages, and is licensed under MIT. Its security modes include SECURE, SAFE, SERVER, and UNSAFE; safe modes do not sanitize generated output or provide a comprehensive security framework.

Who it suits

Asciidoctor suits writers and publishing teams working with AsciiDoc across command-line, Ruby, JVM, or JavaScript environments. Build and editor integrations may also suit teams incorporating document conversion into development workflows.

Good to know, and what to watch

  • Core converters cover HTML5, DocBook 5, and man pages.
  • Runs with Ruby, JVM, or JavaScript.
  • Works on Linux, macOS, and Windows.
  • MIT-licensed and available through several package options.
  • PDF and EPUB 3 converters are separate gems.
  • Safe modes do not sanitize generated output.
  • CLI defaults to UNSAFE mode.

Asciidoctor

Free

Free plan

Getting started

  1. Open the Asciidoctor website
  2. Install it as a RubyGem, Docker image, Linux package, or macOS package
  3. Choose Ruby, AsciidoctorJ on the JVM, or Asciidoctor.js
  4. Process AsciiDoc files or strings through the CLI or Ruby API
  5. Add Maven, Gradle, editor, browser, or diagram integrations as needed

Limits to check

The free plan is the MIT-licensed open-source package. Core converters cover HTML5, DocBook 5, and man pages; PDF and EPUB 3 use separate gems.

The Club's review

Asciidoctor is a free, open-source processor and publishing toolchain for turning AsciiDoc into documentation and other formats. It suits writers and development teams who want to fit document publishing into Ruby, JVM, or JavaScript workflows. Its flexible runtimes and build integrations are a strong foundation, but PDF and EPUB publishing calls for separate converters.

Overview

Asciidoctor processes AsciiDoc files and strings through a command-line interface or Ruby API. The core handles HTML5, DocBook 5, and man pages, while PDF and EPUB 3 conversion come from separate gems. That division works well for teams focused on web documentation or reference output; those producing PDFs or ebooks should expect extra components in their publishing 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 make Asciidoctor suitable for projects that want to automate publishing and incorporate the tool into their own workflows.

Key features

HTML presentation and formats

The default HTML output includes a stylesheet and integrations for Font Awesome, highlight.js, Rouge, Pygments, and MathJax. These integrations give documentation teams options for icons, code highlighting, and mathematical content without changing the input format. The core converter set is broad enough for web and reference documentation, but it does not include PDF or EPUB 3 conversion.

Runtimes and integrations

Asciidoctor runs on Ruby, on the JVM through AsciidoctorJ, and in JavaScript environments through Asciidoctor.js. Maven and Gradle plugins bring it into common build workflows, with additional Javadoc build integration, while browser extensions and an IntelliJ plugin support editor and preview workflows. This range is useful for teams with varied tooling; it also means choosing the runtime and integrations that match a project rather than expecting one interface to cover every environment.

Security modes

Asciidoctor offers UNSAFE, SAFE, SERVER, and SECURE modes. The Ruby API defaults to SECURE, while the command-line interface defaults to UNSAFE, so users should pay attention to the mode used by each entry point. Safe modes do not sanitize generated output and are not a comprehensive security framework; Asciidoctor should not be treated as a complete safeguard when processing untrusted content.

Pricing

Asciidoctor is free: its single 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 paid tier or trial to weigh against it, but PDF and EPUB 3 conversion require separate gems.

Platforms

Asciidoctor works on Linux, macOS, and Windows, and is available through API, extension, web, and self-hosted workflows. Ruby users should note the documented implementations: CRuby 2.3–3.3, JRuby 9.1–9.4, and TruffleRuby (GraalVM). The JVM and JavaScript runtime options extend its reach beyond Ruby, while the command-line interface and Ruby API provide direct ways to process documents.

Who it's for

Asciidoctor is a good fit for writers and development teams already using AsciiDoc who want to publish through build pipelines, editor tools, or multiple runtimes. It is especially practical when HTML5, DocBook, or man-page output meets the need. Teams that require PDF or EPUB should be prepared to add the separate converters, and anyone processing untrusted documents needs security controls beyond Asciidoctor's safe modes.

Pros and cons

  • Multiple runtime choices: Ruby, JVM, and JavaScript support let teams work with Asciidoctor in different language environments.
  • Useful built-in formats: HTML5, DocBook 5, and man pages cover several common documentation outputs without separate converters.
  • Build and editor integrations: Maven, Gradle, Javadoc, browser extensions, and IntelliJ integrations make it easier to fit into existing authoring and publishing workflows.
  • PDF and EPUB need extra components: Separate gems add setup for teams targeting those formats.
  • Safe modes have limits: They do not sanitize output or replace a comprehensive security framework, so untrusted content needs additional care.

Alternatives

Documentation Generators is a directory for comparing tools in the category.

  • StepShot is a freemium macOS option with unlimited capture and editing on its free plan, but that plan exports only the first 10 steps and supports Markdown and HTML export.
  • Scalar is an API-focused alternative with a free plan covering up to 3 APIs, one SDK with up to 25 endpoints, one editor seat, and 50 Agent Scalar credits.
  • Sphinx is a 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.
  • Natural Docs is a free, open-source documentation option under the AGPL version 3 license.
  • Swagger Codegen generates API clients, server stubs, and documentation from OpenAPI specifications.
  • Swift Package Manager is a free, open-source package management tool.
  • Doxygen is a free and open-source option under the GNU General Public License, with Windows, Linux, and macOS downloads.

Verdict

Choose Asciidoctor if you want a free AsciiDoc publishing toolchain that can slot into Ruby, JVM, or JavaScript workflows and automate HTML5, DocBook, or man-page output. Its broad integration options are the main reason to adopt it; look elsewhere or plan for extra converters if PDF or EPUB is central, and do not rely on its safe modes alone to secure untrusted content.

The verdict

Asciidoctor offers several ways to process AsciiDoc and integrate conversion into builds and editors. Users should account for separate PDF and EPUB converters and review security-mode limitations before handling untrusted content.

Questions people ask

Is Asciidoctor free?

Yes. The listed Asciidoctor plan costs nothing, and the project is open source under the MIT License.

Which formats does the core processor convert?

Core converters handle HTML5, DocBook 5, and man pages. PDF and EPUB 3 converters are supplied through separate gems.

Which operating systems are supported?

Asciidoctor works on Linux, macOS, and Windows.

How can it be run?

It runs with Ruby, through AsciidoctorJ on the JVM, or through Asciidoctor.js in JavaScript environments. Processing is available through a command-line interface and Ruby API.

Does it offer integrations?

Yes. The ecosystem includes Maven and Gradle plugins, Javadoc build integration, browser and editor extensions, an IntelliJ plugin, and Asciidoctor Diagram.

What the maker publishes

API and safety
The Ruby API documentation says its default safe mode is :secure. source
Build integrations
The project provides plugins that integrate Asciidoctor with Apache Maven, Gradle and Javadoc builds. source
Built-in converters
The core processor includes built-in converters for HTML5, DocBook 5, and man pages; PDF and EPUB 3 converters are provided by separate gems. source
Distribution
Asciidoctor is distributed as a RubyGem, a Docker image, packages for numerous Linux distributions, and a macOS package through Homebrew and MacPorts. source
Distribution
Asciidoctor is distributed as a Ruby gem, Docker image, Linux packages, and macOS packages through Homebrew and MacPorts. source
Editor integrations
Asciidoctor.js powers AsciiDoc preview extensions for Chrome, Atom, Brackets and other web-based tools. source
Founded
2012 source
HTML features
Its default HTML experience includes a stylesheet and integrations for Font Awesome, highlight.js, Rouge, Pygments, and MathJax. source
HTML integrations
Its default HTML output includes Font Awesome, highlight.js, Rouge, Pygments and MathJax integrations. source
Integrations
The project ecosystem includes Maven and Gradle plugins, browser extensions, an IntelliJ plugin, and tools such as Asciidoctor Diagram. source
Intended users
The project describes its goal as providing an accessible, comprehensive, open source toolchain and workbench for writing and publishing AsciiDoc across platforms and runtimes. source
Intended users
The project describes its toolchain as serving people who write and publish AsciiDoc content across platforms and runtimes. source
Interfaces
The processor provides a command line interface and a Ruby API for processing documents. source
License
Asciidoctor use is granted under the MIT License. source
License
The processor is open source software available under the MIT license. source
Operating systems
The site says Asciidoctor works on Linux, macOS, and Windows. source
Operating systems
The project says Asciidoctor works on Linux, macOS and Windows. source
Output formats
The core processor includes HTML 5, DocBook 5 and man page converters; PDF and EPUB 3 converters are provided separately. source
Purpose
Asciidoctor is an open source text processor and publishing toolchain for converting AsciiDoc into HTML5, DocBook, PDF, EPUB 3, manual pages, and other formats. source
Purpose
Asciidoctor parses AsciiDoc source and converts it into publishable formats such as HTML 5 and PDF. source
Requirements
The documented Ruby implementations are CRuby 2.3–3.3, JRuby 9.1–9.4, and TruffleRuby (GraalVM). source
Runtime options
Asciidoctor can run using Ruby, a JVM through AsciidoctorJ, or JavaScript through Asciidoctor.js. source
Runtimes
Asciidoctor runs on Ruby, on the JVM through AsciidoctorJ, and in JavaScript environments through Asciidoctor.js. source
Security limitation
The project states that safe modes do not sanitize generated output and are not a comprehensive security framework. source

Checked against the maker's pages on 4 Oct 2026.