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.

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.

This document is also available in the following languages:
汉语 | Deutsch | Français | 日本語

• What is AsciiDoc?

• AsciiDoc Writer’s Guide

• Asciidoctor User Manual

• AsciiDoc Syntax 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.

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.

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 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.

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.

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.

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.

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

• CRuby (aka MRI) 2.3 - 2.6

• JRuby 9.1 - 9.2

• TruffleRuby (GraalVM)

• Opal (JavaScript)

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 or if you’ll be installing additional gems), (d) the Asciidoctor Docker image, or (e) Bundler.

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.

(a) Linux package managers

$ sudo apk add asciidoctor

$ sudo pacman -S asciidoctor

$ sudo apt-get install -y asciidoctor

$ sudo dnf install -y asciidoctor

(b) Homebrew (macOS)

$ brew install asciidoctor

(c) Windows

choco install ruby

(d) gem install

$ gem install asciidoctor

$ gem install asciidoctor --pre

(e) Docker

(f) 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

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.

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).

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 the Asciidoctor Project.

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.

Chat (Gitter)

Discussion list (Nabble)

https://discuss.asciidoctor.org

Twitter

#asciidoctor hashtag or @asciidoctor mention

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

Copyright © 2012-2020 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 and based on a prototype written by Nick Hengeveld.

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

AsciiDoc is a Trademark of the Eclipse Foundation, Inc.

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