Installing the Toolchain

> Asciidoctor > Asciidoctor Documentation >

Asciidoctor, an implementation of the AsciiDoc processor written in Ruby, is a drop-in replacement for AsciiDoc in most cases. Asciidoctor provides a command line tool and a Ruby API for converting AsciiDoc documents to HTML 5, Docbook 5.0, DocBook 4.5 and custom output formats.

System Requirements

Asciidoctor works on Linux, OS X (aka Mac OS X) and Windows.

Asciidoctor requires one of the following implementations of Ruby:

  • Ruby 1.8.7

  • Ruby 1.9.3

  • Ruby 2 (2.0.0 or better)

  • JRuby 1.7 (Ruby 1.8 and 1.9 modes)

  • JRuby 9000

  • Rubinius 2.0 (Ruby 1.8 and 1.9 modes)

  • Opal (Javascript)

We expect Asciidoctor to work with other versions of Ruby as well. We welcome your help testing those versions if you are interested in seeing them supported.

Installing the Asciidoctor RubyGem

Asciidoctor can be installed using the gem command, Bundler or a Linux package manager.

Install using gem

To install Asciidoctor using the gem command:

  1. Open a terminal

  2. Type the following gem command

    $ gem install asciidoctor

If the Asciidoctor gem installed successfully, the asciidoctor command line interface (CLI) will be available on your PATH. To confirm that Asciidoctor is available, execute:

$ asciidoctor --version

The following output should appear in your terminal:

Asciidoctor 1.5.4 [http://asciidoctor.org]
Runtime Environment (ruby 2.3.0p0 [x86_64-linux]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)
Alternate Entry Points

In addition to the command line interface, Asciidoctor provides a Ruby API. The API is intended for integration with other software projects and is suitable for server-side applications, such as Rails, Sinatra and GitHub.

Asciidoctor also has a Java API that mirrors the Ruby API. The Java API calls through to the Ruby API using an embedded JRuby runtime. See the AsciidoctorJ project for more information.

Install using Bundler

To install Asciidoctor for a project using Bundler:

  1. Open your project’s Gemfile

  2. Add the asciidoctor gem using:

    gem 'asciidoctor'

  3. Save the Gemfile

  4. Open a terminal

  5. Install the gem using the bundle command:

    $ bundle

Install using yum or dnf on Fedora

To install Asciidoctor on Fedora (or RHEL via EPEL) using the rubygem-asciidoctor package:

  1. Open a terminal

  2. Run the installation command

    On Fedora 21 or earlier
    $ sudo yum install asciidoctor
    On Fedora 22 or later
    $ sudo dnf install asciidoctor

The benefit of installing the gem using this method is that the package manager will also install Ruby and RubyGems if not already on your machine.

Install using apt-get on Debian or Ubuntu

To install Asciidoctor on Debian Sid or Ubuntu Saucy or greater:

  1. Open a terminal

  2. Type the following apt-get command using sudo:

    $ sudo apt-get install asciidoctor

The benefit of installing the gem via apt-get is that the package manager will also install Ruby and RubyGems if not already on your machine.

Install using apk on Alpine Linux

To install Asciidoctor on Alpine Linux using the asciidoctor package:

  1. Open a terminal

  2. Type the following apk command using sudo:

    $ sudo apk add asciidoctor

The benefit of installing the gem via apk is that the package manager will also install Ruby and RubyGems if not already on your machine.

Upgrading the Asciidoctor Ruby Gem

If you have an earlier version of Asciidoctor installed, you can update the gem using the gem command:

$ gem update asciidoctor

If you accidentally use gem install instead of gem update, then you’ll end up with both versions installed. To remove the older version, use the following gem command:

$ gem cleanup asciidoctor

On Fedora, you can update the package using:

On Fedora 21 or earlier
$ sudo yum update asciidoctor
On Fedora 22 or later
$ sudo dnf update asciidoctor
Your Fedora system may be configured to automatically update packages, in which case no further action is required by you. Refer to the Fedora docs if you are unsure.

On Debian or Ubuntu, you can update the package using:

$ sudo apt-get upgrade asciidoctor

On Alpine Linux, you can update the package using:

$ sudo apk add --upgrade asciidoctor
The Linux packages may not be available right away after a release of the gem. It may take several weeks for the packages to be updated. If you need to upgrade to the latest version immediately, use the gem install option documented above.

Text editors and syntax highlighting

Since AsciiDoc syntax is just plain text, you can write an AsciiDoc document using any text editor. You don’t need complex word processing programs like Microsoft Word, OpenOffice Writer or Google Docs. In fact, you shouldn’t use these programs because they add cruft to your document that you can’t see that makes conversion tedious.

While it’s true any text editor will do, an editor that supports syntax highlighting for AsciiDoc may be more helpful. The color brings contrast to the text, making it easier to read. The highlighting also confirms when you’ve entered the correct syntax for an inline or block element.

The most popular application for editing plain text on OS X is TextMate. A similar choice on Linux is GEdit. On Windows, stay away from Notepad and Wordpad because they produce plain text which is not cross-platform friendly. Opt instead for a competent text editor like Notepad++. If you’re a programmer (or a writer with an inner geek), you’ll likely prefer Vim, Emacs, or Sublime Text, all of which are available cross-platform. For those that work on multiple platforms, Atom is a consistent choice with many add-on packages for working with AsciiDoc files. The key feature all these editors share is syntax highlighting for AsciiDoc.

Previewing the output of the document while editing can be helpful. To learn how to setup instant preview, check out the Editing AsciiDoc with Live Preview tutorial.

Open up your favorite text editor and get ready to write some AsciiDoc!

Next steps and help

Now that you have installed Asciidoctor, you may want to learn more about the AsciiDoc syntax and the growing variety of integrations, backends, and customizations the Asciidoctor project is developing.

Need an overview of the AsciiDoc syntax?

Want to dive deep into the details of the syntax?

Are you ready to convert your AsciiDoc document into HTML, DocBook or PDF?

If you’re writing software documentation, you’ll probably want to also install a source highlighter or learn how to activate client-side libraries that perform source highlighting on source code blocks.

Interested in building a theme from the Asciidoctor Stylesheet Factory or applying a custom stylesheet?

Additional guides are listed on the Documentation page. Also, don’t forget to join the Asciidoctor mailing list, where you can ask questions and leave comments.