AsciiDoc was started by Stuart Rackham and has received contributions from many individuals in the AsciiDoc community.

Copyright © 2012-2019 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.

Asciidoctor is developed to help you easily write and publish your content. But we can’t do it without your feedback! We encourage you to ask questions and discuss any aspects of the project on the discussion list, on Twitter or in the chat room.

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

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.

However you go about it, you can have 100% control over the output. For more information about how to use the API or to customize the output, refer to the user manual .

One easy way to customize the output piecemeal is by using the template converter. The template converter allows you to supply a Tilt -supported template file to handle converting any node in the document.

Keep in mind that if you don’t like the output Asciidoctor produces, you can change it! Asciidoctor supports custom converters that can handle converting from the parsed document to the generated output.

If you need access to the parsed document, you can split the conversion into discrete steps:

If you want the full HTML document, enable the header_footer option as follows:

You can also convert an AsciiDoc string to embeddable HTML (for inserting in an HTML page) using:

You can then convert an AsciiDoc source file to an HTML file using:

To use Asciidoctor in your application, you first need to require the gem:

Refer to the following resources to learn more about how to use the asciidoctor command.

For instance, to write the file to a different directory, use:

You can control the Asciidoctor processor by adding various flags and switches, which you can learn about using:

The following command converts the file README.adoc to HTML and saves the result to the file README.html in the same directory. The name of the generated HTML file is derived from the source file by changing its file extension to .html .

The asciidoctor command allows you to invoke Asciidoctor from the command line (i.e., a terminal).

Asciidoctor also provides an API. The API is intended for integration with other Ruby software, such as Rails, Sinatra and GitHub, and other languages, such as Java (via AsciidoctorJ ) and JavaScript (via Asciidoctor.js ).

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

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:

When you install a new version of the gem using gem install , you end up with multiple versions installed. Use the following command to remove the old versions:

If you previously installed Asciidoctor using the gem command, you’ll need to manually upgrade Asciidoctor when a new version is released. You can upgrade the gem by typing:

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.

To upgrade the gem, specify the new version in the Gemfile and run bundle again. Using bundle update (without specifying a gem) is not recommended as it will also update other gems, which may not be the desired result.

Create a Gemfile in the root folder of your project (or the current directory)

Before installing Asciidoctor using gem install , you should use RVM to install Ruby in your home directory (i.e., user space). Then, you can safely use the gem command to install or update the Asciidoctor gem. When using RVM, gems are installed in a location isolated from the system.

Or you use the Rubyinstaller , download the package for your Windows Version and after the installation go ahead with gem installation instructions .

When you already use chocolatey on your machine, you can use:

To use Asciidoctor with Windows, you have two easy options.

You can use Homebrew, the macOS package manager, to install Asciidoctor. If you don’t have Homebrew on your computer, complete the installation instructions at brew.sh first. Once Homebrew is installed, you’re ready to install the asciidoctor gem. Open a terminal and type:

On RPM-based Linux distributions, such as Fedora, CentOS, and RHEL, use the DNF package manager to install Asciidoctor. To install the package, open a terminal and type:

On Debian and Debian-based distributions such as Ubuntu, use APT to install Asciidoctor. To install the package, open a terminal and type:

If you want to use a version of Asciidoctor that is newer than what is installed by the package manager, see the gem installation instructions .

The version of Asciidoctor installed by the package manager may not match the latest release of Asciidoctor. Consult the package repository for your distribution to find out which version is packaged per distribution release.

The benefit of using your operating system’s package manager to install the gem is that it handles installing Ruby and the RubyGems library if those packages are not already installed on your machine.

Asciidoctor can be installed using (a) package managers for popular Linux distributions, (b) Homebrew for macOS, (c) the gem install command (recommended for Windows users), (d) the Asciidoctor Docker image, or (e) Bundler.

Once you make this change, all your Unicode headaches will be behind you. If you’re using an IDE like Eclipse, make sure you set the encoding to UTF-8 there as well. Asciidoctor works best when you use UTF-8 everywhere.

If you’re using a non-English Windows environment, you may bump into an Encoding::UndefinedConversionError when invoking Asciidoctor. To solve this issue, we recommend changing the active code page in your console to UTF-8:

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

Asciidoctor also runs in JavaScript. Opal is used to transcompile the Ruby source to JavaScript to produce Asciidoctor.js . Asciidoctor.js is a fully-functional version of Asciidoctor that works in any JavaScript environment, such as a web browser or Node.js. It’s used to power the AsciiDoc preview extensions for Chrome, Atom, Brackets and other web-based tooling.

You can run Asciidoctor on the JVM using JRuby. To invoke the Asciidoctor API directly from Java and other JVM languages, use AsciidoctorJ . There are plugins available for Apache Maven , Gradle , and Javadoc , which allow you to integrate AsciiDoc processing directly into your build using AsciidoctorJ.

In addition to the classic AsciiDoc syntax, Asciidoctor recognizes additional markup and formatting options, such as font-based icons (e.g., icon:fire[] ) and UI elements (e.g., button:[Save] ). Asciidoctor also offers a modern, responsive theme based on Foundation to style the HTML5 output.

Asciidoctor is a drop-in replacement for its predecessor, AsciiDoc Python ( asciidoc.py ). The Asciidoctor test suite has > 2,350 tests to ensure compatibility with the AsciiDoc syntax.

Asciidoctor reads and parses text written in the AsciiDoc syntax, then feeds the parse tree to a set of built-in converters to produce HTML5, DocBook 5, and man(ual) page output. You have the option of using your own converter or loading Tilt -supported templates to customize the generated output or produce additional formats.

Asciidoctor reads content written in plain text, as shown in the panel on the left in the image below, and converts it to HTML5, as shown rendered in the right panel. Asciidoctor applies a default stylesheet to the HTML5 document to provide a pleasant out-of-the-box experience.

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

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.

To simplify installation, Asciidoctor is packaged and distributed as a RubyGem (aka gem) to RubyGems.org . It’s also distributed as a package for popular Linux distributions and macOS. In addition to running on Ruby, Asciidoctor can be executed on a JVM using AsciidoctorJ or in any JavaScript environment (including the browser) using Asciidoctor.js .

Asciidoctor is a fast, open source text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook, PDF, and other formats. Asciidoctor is written in Ruby and runs on all major operating systems. The Asciidoctor project is hosted on GitHub .

Use AsciiDoc for document markup. Really. It's actually readable by humans, easier to parse and way more flexible than XML. — Linus Torvalds

Asciidoctor Project

The Asciidoctor project is an effort to bring a comprehensive and accessible publishing toolchain, centered around the AsciiDoc syntax, to a growing range of ecosystems, including Ruby, JavaScript and the JVM.



In addition to an AsciiDoc processor and a collection of stylesheets, the project provides plugins for Maven, Gradle and Guard and packages for operating systems such as Fedora, Debian and Ubuntu. It also pushes AsciiDoc to evolve by introducing new ideas and innovation and helps promote AsciiDoc through education and advocacy.

Contribute to asciidoctor.org

This website is open source! The source is hosted under the Asciidoctor organization on GitHub.

If you want to help by improving upon it, fork the project, revise the content, then send a pull request. When the pull request is merged, the site will be updated automatically.