Install Asciidoctor PDF

Asciidoctor PDF is a Ruby application. Therefore, you’ll need a Ruby runtime to run it.

The Ruby versions on which Asciidoctor PDF is supported and tested are Ruby 2.7 or greater or JRuby 9.2 or greater. We always recommend using the most recent version of Ruby or JRuby, if possible. If you attempt to use an unsupported version of Ruby with Asciidoctor PDF, the conversion will likely fail in unexpected ways.

All required libraries (i.e., gems) will be installed automatically when you install Asciidoctor PDF, which is covered in the next section. You must install any optional dependencies yourself in order to activate the corresponding optional features.

To check if you have Ruby available, run the ruby command to print the installed version:

Make sure this command reports a Ruby version that starts with at least 2.7 (or a JRuby version that starts with at least 9.2). If so, you’re ready to proceed. If not, head over to rvm.io to get RVM and use it to install Ruby.

Asciidoctor PDF (gem: asciidoctor-pdf, command: asciidoctor-pdf) is published as a RubyGem to the rubygems.org software registry. You install Asciidoctor PDF from that registry using the RubyGem management tools provided by Ruby (bundle or gem). Alternately, you can build and install Asciidoctor PDF from source.

Refer to the table below for instructions on how to install Asciidoctor PDF. If you use Bundler to manage your gems in a Gemfile, add the entry listed in the Bundler column. Otherwise, run the command in the gem command column.

Installing Asciidoctor PDF will automatically install a number of additional gems mentioned in these docs, including asciidoctor, prawn, prawn-svg, prawn-table, prawn-icon, and ttfunk. The versions of these required dependencies are locked to the version of Asciidoctor PDF.

If you get a permission error while installing the gem, such as the one below, it’s likely you’re attempting to install the gem directly into your system. Installing gems for tech writing directly into your system is not recommended.

A better practice (and one that will ensure your sanity) is to ignore any version of Ruby installed on your system and use RVM to manage the Ruby installation instead. The benefit of this approach is that a) Ruby is guaranteed to be set up correctly, b) installing gems will in no way interfere with the operation of your system, and c) any bin scripts provided by the installed gems will be available on your PATH. All files are managed in user space (aka your home or user directory). If something gets messed up, you can simply remove the $HOME/.rvm folder and start over.

To learn how to install RVM, follow the RVM installation procedure covered in the Asciidoctor documentation. Once you have installed RVM, install a version of Ruby:

Then switch to that version and set it as the default:

You only need to install the version of Ruby once. Each time you open a new terminal, be sure to select the default Ruby.

After installing the asciidoctor-pdf gem, you can see where it was installed using the following command:

To see where the bin script is located, use this command:

Both paths should be underneath the $HOME/.rvm directory. If not, check your RVM setup.

There are several optional features of this converter that require additional gems to be installed. Those features are as follows.

The following table lists the optional dependencies of Asciidoctor PDF, including Asciidoctor extensions which are tested with this converter. The name of the dependency and its gem name are listed along with the minimum supported version and what feature or features it enables when installed (and, if necessary, required).