Asciidoctor PDF: A native PDF converter for AsciiDoc
Asciidoctor PDF is a native PDF converter for AsciiDoc that serves the
The documentation for the latest, stable release of Asciidoctor PDF is available at https://docs.asciidoctor.org/pdf-converter/latest/.
If you’re looking for the documentation for Asciidoctor PDF 1.6, refer to the README in the v1.6.x branch. Asciidoctor PDF 1.6 is no longer being developed and will reach EOL later this year. You are encouraged to migrate to Asciidoctor PDF 2 as soon as possible.
- Install Asciidoctor PDF
- Optional dependencies
- Run the Application
Asciidoctor PDF converts an AsciiDoc document directly to a PDF document. The style and layout of the PDF are controlled by a dedicated theme file. To the degree possible, Asciidoctor PDF supports all the features of AsciiDoc that are supported by Asciidoctor. It also provides PDF-specific features. However, there are certain limitations imposed by the PDF format and the PDF library this extension uses.
Asciidoctor PDF uses the Prawn gem and Prawn’s extensions, such as prawn-svg and prawn-table, to generate a PDF document. Prawn is a general purpose PDF generator for Ruby that features high-level APIs for common needs like setting up the page and inserting images and low-level APIs for positioning and rendering text and graphics.
|For the latest Asciidoctor PDF features and fixes, see What’s New in Asciidoctor PDF.|
Asciidoctor PDF is built on Asciidoctor. Like Asciidoctor, Asciidoctor PDF is a Ruby application. Therefore, to use it, you’ll need a Ruby runtime.
The supported Ruby runtimes are Ruby 2.7 or greater and JRuby 9.2 or greater. However, we always recommend using the most recent release of Ruby or JRuby. All required libraries (i.e., gems) will be installed automatically when you install Asciidoctor PDF, which will be covered in the next section.
To check if you have Ruby available, run the
ruby command to print the installed version:
$ ruby -v
Make sure this command reports a Ruby version that starts with 2.7 (or a JRuby version that starts with 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.
Install Asciidoctor PDF
You can install Asciidoctor PDF using the
gem install command.
We’ll use this command to install the Asciidoctor PDF gem named asciidoctor-pdf that’s published on RubyGems.org.
Pass the name of the gem to the
gem install command as follows:
$ gem install asciidoctor-pdf
Installing Asciidoctor PDF will install a number of other gems mentioned in these docs, including asciidoctor, prawn, prawn-svg, prawn-table, prawn-icon, and ttfunk. For the most part, the versions of these dependencies are locked to the version of Asciidoctor PDF. The patch versions are allowed to vary. Please note that the minimum supported version of the asciidoctor gem (Asciidoctor) is 2.0.10.
Install a prerelease or development version
To install the latest prerelease of the asciidoctor-pdf gem from RubyGems.org (if a prerelease is available), use the following command:
$ gem install asciidoctor-pdf --pre
You can also run the code from source if you want to use a development version or participate in development.
There are several optional features of this converter that require additional gems to be installed. Those features are as follows.
- Source highlighting
You’ll need to install a syntax highlighter to use source highlighting (build-time only).
- PDF optimization
If you want to optimize your PDF, you’ll need rghost or hexapdf. See Optimize the PDF for installation and usage instructions.
- Automatic hyphenation
To turn on automatic hyphenation using the
hyphensattribute, you’ll need to install the
$ gem install text-hyphen
- Accelerated image decoding
Ruby is not particularly fast at decoding images, and the image formats it supports are limited. To help, you can install prawn-gmagick, which delegates the work of decoding images to GraphicsMagick. Refer to Supporting additional image file formats for instructions about how to enable this integration.
Check the minimum supported version table to make sure you’re using a supported version of the dependency.
Run the Application
Assuming all the required gems install properly, verify you can run the
$ asciidoctor-pdf -v
If you see the version of Asciidoctor PDF printed, you’re ready to use Asciidoctor PDF!
Let’s grab an AsciiDoc document to distill and start putting Asciidoctor PDF to use.
If you don’t already have an AsciiDoc document to work with, you can use the basic-example.adoc file found in the examples directory of this project. Copy it to the current directory as follows:
$ cp examples/basic-example.adoc .
Let’s take a look at the contents of that file.
It’s time to convert the AsciiDoc document directly to PDF.
Convert AsciiDoc to PDF
You’ll need the
Converting to PDF is as straightforward as running the
asciidoctor-pdf script using Ruby and passing the AsciiDoc document as the first argument:
$ asciidoctor-pdf basic-example.adoc
This command is a shorter way of running
asciidoctor with the PDF converter and backend enabled:
$ asciidoctor -r asciidoctor-pdf -b pdf basic-example.adoc
asciidoctor-pdf command saves you from having to remember these low-level options.
That’s why we provide it.
When the script completes, you should see the file basic-example.pdf in the current directory. Asciidoctor creates the output file in the same directory as the input file by default. Open the basic-example.pdf file with a PDF viewer to see the result.
For more information about how to use Asciidoctor PDF and PDF-specific AsciiDoc syntax, see the Asciidoctor PDF documentation.
The layout and styling of the PDF is driven by a YAML configuration file. To learn how the theming system works and how to create and apply custom themes, refer to the Asciidoctor PDF theming documentation.