Asciidoctor
asciidoctor.org
- Free plan
- Windows
- macOS
- Linux
- Web
- Browser extension
- API
- Self-hosted
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.
Plans
Every plan and priceAsciidoctor
Free plan
Getting started
- Open the Asciidoctor website
- Install it as a RubyGem, Docker image, Linux package, or macOS package
- Choose Ruby, AsciidoctorJ on the JVM, or Asciidoctor.js
- Process AsciiDoc files or strings through the CLI or Ruby API
- 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.