Asciidoctor is a fast, open source, Ruby-based text processor for parsing AsciiDoc® into a document model and converting it to output formats such as HTML 5, DocBook 5, manual pages, PDF, EPUB 3, and other formats.

Asciidoctor also has an ecosystem of extensions, converters, build plugins, and tools to help you author and publish content written in AsciiDoc. You can find the documentation for these projects at https://docs.asciidoctor.org.

In addition to running on Ruby, Asciidoctor can be executed on a JVM using AsciidoctorJ or in any JavaScript environment using Asciidoctor.js.

This document is also available in the following languages:
简体中文 | Deutsch | Français | 日本語

• Asciidoctor Documentation

• AsciiDoc Language Documentation

• AsciiDoc Syntax Quick Reference

We want to recognize our sponsors for their commitment to improving the state of technical documentation by supporting this project. Thank you sponsors! Without your generous support, Asciidoctor would not be possible.

You can support this project by becoming a sponsor through OpenCollective.

AsciiDoc is the language.
Asciidoctor is the processor.

Asciidoctor reads the AsciiDoc source, as shown in the panel on the left in the image below, and converts it to publishable formats, such as HTML 5, as shown rendered in the panel on the right.

Asciidoctor provides built-in converters for three output formats by default: HTML 5, DocBook 5, and man page (short for manual page). Additional converters, such as PDF and EPUB 3, are provided by separate gems. Asciidoctor also provides an out-of-the-box HTML experience complete with a default stylesheet and built-in integrations like Font Awesome (for icons), highlight.js, Rouge, and Pygments (for source highlighting), and MathJax (for STEM processing).

Although Asciidoctor is written in Ruby, it does not mean you need Ruby to use it. Asciidoctor can be executed on a JVM using AsciidoctorJ or in any JavaScript environment (including the browser) using Asciidoctor.js.

Installing an Asciidoctor processor is just the beginning of your publishing experience. Asciidoctor gives you access to a ecosystem of extensions and tools, ranging from add-on converters, to extended syntax, to build plugins, to integrated writing and preview environments:

• Asciidoctor Diagram

• Maven plugin and site module

• Gradle plugin

• Asciidoclet

• reveal.js converter

• EPUB 3 converter

• IntelliJ plugin

• web browser extensions

• and more

Asciidoctor is the successor to AsciiDoc.py. If you’re using AsciiDoc.py, see Migrate from AsciiDoc.py to learn how to upgrade to Asciidoctor.

Asciidoctor works on Linux, macOS and Windows and requires one of the following implementations of Ruby:

• CRuby (aka MRI) 2.7 - 3.2

• JRuby 9.2 - 9.4

• TruffleRuby (GraalVM)

Asciidoctor is packaged and distributed to RubyGems.org as a RubyGem (aka gem) named asciidoctor. The asciidoctor gem can be installed on all major operating systems using Ruby packaging tools (gem or bundle). Asciidoctor is also distributed as a Docker image, as a package for numerous Linux distributions, and as a package for macOS (via Homebrew and MacPorts).

Linux package managers

$ sudo apk add asciidoctor

$ sudo pacman -S asciidoctor

$ sudo apt-get install -y asciidoctor

$ sudo dnf install -y asciidoctor

macOS

$ brew install asciidoctor

$ sudo port install asciidoctor

Windows

choco install ruby

gem install

$ gem install asciidoctor

$ gem install asciidoctor --pre

Docker

Bundler

If you installed Asciidoctor using a package manager, your operating system is probably configured to automatically update packages, in which case you don’t need to update the gem manually.

apk (Alpine Linux)

$ sudo apk add -u asciidoctor

APT

$ sudo apt-get upgrade -y asciidoctor

DNF

$ sudo dnf update -y asciidoctor

Homebrew (macOS)

$ brew update
$ brew upgrade asciidoctor

MacPorts (macOS)

$ sudo port selfupdate
$ sudo port upgrade asciidoctor

gem install

$ gem install asciidoctor

$ gem cleanup asciidoctor

If the Asciidoctor gem installed successfully, the asciidoctor command line interface (CLI) will be available on your PATH. To verify it’s available, run the following in your terminal:

You should see information about the Asciidoctor version and your Ruby environment printed in the terminal.

Command line interface (CLI)

$ asciidoctor README.adoc

$ asciidoctor --help

$ asciidoctor -D output README.adoc

Ruby API

require 'asciidoctor'

Asciidoctor.convert_file 'README.adoc', to_file: true, safe: :safe

content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
Asciidoctor.convert content, safe: :safe

content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
html = Asciidoctor.convert content, header_footer: true, safe: :safe

content = '_Zen_ in the art of writing https://asciidoctor.org[AsciiDoc].'
document = Asciidoctor.load content, header_footer: true, safe: :safe
puts document.doctitle
html = document.convert

New contributors are always welcome! If you discover errors or omissions in the source code, documentation, or website content, please don’t hesitate to submit an issue or open a pull request with a fix.

Here are some ways you can contribute:

• by using prerelease (alpha, beta or preview) versions

• by reporting bugs

• by suggesting new features

• by writing or editing documentation

• by writing code with tests — No patch is too small.

  • fix typos

  • add comments

  • clean up inconsistent whitespace

  • write tests!

• by refactoring code

• by fixing issues

• by reviewing patches

The Contributing guide provides information on how to create, style, and submit issues, feature requests, code, and documentation to Asciidoctor.

Asciidoctor is developed to help you easily write and publish your content. But we can’t do it without your input. If you need assistance or want to provide feedback, please follow the links to the resources listed on the Get Help page in the docs. Here’s a quick summary:

Project chat (Zulip)

https://chat.asciidoctor.org

Discussion list (archived)

https://discuss.asciidoctor.org

Social media (Twitter)

Follow @asciidoctor or search the #asciidoctor hashtag

Further information and documentation about Asciidoctor can be found on the project’s website.

Home | News | Docs

The Asciidoctor organization on GitHub hosts the project’s source code, issue tracker, and sub-projects.

Source repository (git)

https://github.com/asciidoctor/asciidoctor

Issue tracker

https://github.com/asciidoctor/asciidoctor/issues

Asciidoctor organization on GitHub

https://github.com/asciidoctor

The core Asciidoctor project is governed by the Code of Conduct for the Asciidoctor community of projects. By participating, you’re agreeing to honor this code. Let’s work together to make this a welcoming, professional, inclusive, and safe environment for everyone.

This project adheres to semantic versioning (major.minor.patch). Typically, patch releases are only made for the current minor release. However, exceptions are made on a case-by-case basis to address security vulnerabilities and other high-priority issues.

Copyright © 2012-present Dan Allen, Sarah White, Ryan Waldron, and the individual contributors to Asciidoctor. Use of this software is granted under the terms of the MIT License.

See the LICENSE for the full license text.

Asciidoctor is led by Dan Allen and Sarah White and has received contributions from many individuals in Asciidoctor’s awesome community. The project was initiated in 2012 by Ryan Waldron based on a prototype written by Nick Hengeveld for the Git website.

AsciiDoc.py was started and maintained by Stuart Rackham from 2002 to 2013 and has received contributions from many individuals in the AsciiDoc.py community.

AsciiDoc® and AsciiDoc Language™ are trademarks of the Eclipse Foundation, Inc.

Refer to the CHANGELOG for a complete list of changes in older releases.