Jekyll One

Asciidoctor PDF is a native PDF converter for AsciiDoc that plugs into the PDF backend. It bypasses the requirement to generate an intermediary format such as DocBook, Apache FO, or LaTeX. Instead, you can use Asciidoctor PDF to convert your documents directly from AsciiDoc to PDF. The aim of this library is to take the pain out of creating PDF documents from AsciiDoc.

Asciidoctor PDF is made possible by an amazing Ruby gem named Prawn. And what a gem it is! Prawn is a nimble PDF writer for Ruby. More important, it’s a hackable platform that offers both high level APIs for the most common needs and low level APIs for bending the document model to accommodate special circumstances.

Asciidoctor PDF is currently alpha software. While the converter handles most AsciiDoc content, there’s still work needed to fill in gaps where conversion is incomplete, incorrect or not implemented. See the milestone v1.5.0 in the Issue tracker for details.

With Prawn, you can write text, draw lines and shapes and place images anywhere on the page and add as much color as you like. In addition, it brings a fluent API and aggressive code re-use to the printable document space.

Here’s an example that demonstrates how to use Prawn to create a basic PDF document.

Create a basic PDF document using Prawn 
require 'prawn'
Prawn::Document.generate 'output.pdf' do
  text 'Hello, PDF creation!'
end

It’s that easy. And that’s just the beginning.

Prawn is the killer library for PDF generation we’ve needed to close this critical gap in Asciidoctor. It absolutely takes the pain out of creating printable documents. Picking up from there, Asciidoctor PDF takes the pain out of creating PDF documents from AsciiDoc.

Highlights

  • Direct AsciiDoc to PDF conversion

  • SVG support

  • PDF document outline (i.e., bookmarks)

  • Table of contents page(s)

  • Document metadata (title, authors, subject, keywords, etc)

  • Internal cross reference links

  • Syntax highlighting with Rouge, Pygments, or CodeRay

  • Page numbering

  • Customizable running content (header and footer)

  • “Keep together” blocks (i.e., page breaks avoided in certain block content)

  • Orphaned section titles avoided

  • Autofit verbatim blocks (as permitted by base_font_size_min setting)

  • Table border settings honored

  • Font-based icons

  • Custom (TTF) fonts

  • Double-sided printing mode (margins alternate on recto and verso pages)

Prerequisites

All that’s needed is Ruby (1.9.3 or above; 2.3.x recommended) and a few Ruby gems, which we explain how to install in the next section.

To check if you have Ruby available, use the ruby command to query the version installed:

ruby --version

By default, Asciidoctor PDF automatically installs the latest version of Prawn if you don’t already have Prawn installed. This will fail on older versions of Ruby. To workaround, you need to install certain dependencies first.

Starting with Prawn 2.0.0, Prawn requires Ruby >= 2.0.0 during installation. Therefore, to use Asciidoctor PDF with Ruby 1.9.3, you must first explicitly install the following dependencies to lock the versions:

gem install prawn --version 1.3.0
gem install addressable --version 2.4.0
gem install prawn-svg --version 0.21.0
gem install prawn-templates --version 0.0.3

You can then proceed with installation of Asciidoctor PDF on Ruby 1.9.3.

Starting with Prawn 2.2.0, Prawn requires Ruby >= 2.1.0 during installation. Therefore, to use Asciidoctor PDF with Ruby 2.0.0, you must first explicitly install the following dependencies to lock the versions:

gem install prawn --version 2.1.0
gem install prawn-svg --version 0.26.0
gem install prawn-templates --version 0.0.4

For all other versions of Ruby, you can simply install the Asciidoctor PDF gem. It will transitively install the required dependencies.

System Encoding

Asciidoctor assumes you’re using UTF-8 encoding. To minimize encoding problems, make sure the default encoding of your system is set to UTF-8.

If you’re using a non-English Windows environment, the default encoding of your system may not be UTF-8. As a result, you may get an Encoding::UndefinedConversionError or other encoding issues when invoking Asciidoctor. To solve these problems, we recommend at least changing the active code page in your console to UTF-8.

chcp 65001

Once you make this change, all your Unicode headaches will be behind you.

Getting Started

You can get Asciidoctor PDF by installing the published gem or running the code from source.

Install the Published Gem

Asciidoctor PDF is published as a pre-release on RubyGems.org. First, make sure you have satisfied the prerequisites. Then, you can install the published gem using the following command:

gem install asciidoctor-pdf --pre

If you want to syntax highlight source listings, you’ll also want to install Rouge, Pygments, or CodeRay. Choose one (or more) of the following:

Rouge (preferred)
gem install rouge
Pygments
gem install pygments.rb
CodeRay
gem install coderay

You then activate syntax highlighting for a given document by adding the source-highlighter attribute to the document header (Rouge shown):

:source-highlighter: rouge

Assuming all the required gems install properly, verify you can run the asciidoctor-pdf script:

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!

An example AsciiDoc document

If you don’t already have an AsciiDoc document, you can use the basic_example.adoc file found in the examples directory of this project.

It’s time to convert the AsciiDoc document directly to PDF.

Convert AsciiDoc to PDF

You’ll need the rouge gem installed to run this example since it uses the source-highlighter attribute with the value of rouge.

Converting to PDF is a simple as running the asciidoctor-pdf script using Ruby and passing our AsciiDoc document as the first argument.

asciidoctor-pdf 000_basic_example.adoc

This command is just a shorthand way of running:

asciidoctor -r asciidoctor-pdf -b pdf 000_basic_example.adoc

The asciidoctor-pdf command just saves you from having to remember all those flags. That’s why we created it.

When the script completes, you should see the file 000_basic_example.pdf in the same directory. Open the 000_basic_example.pdf file with a PDF viewer to see the result.

Example PDF document rendered in a PDF viewer
Example PDF document rendered in a PDF viewer

You’re also encouraged to try converting the documents in the examples directory to see more of what Asciidoctor PDF can do. The pain of the DocBook toolchain should be melting away from now.

Themes

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 Theme Guide. You can use the built-in theme files, which you can find in the data/themes directory, as examples.

Support for Non-Latin Languages

Asciidoctor can process the full range of characters in the UTF-8 character set. That means you can write your document in any language, save the file with UTF-8 encoding, and expect Asciidoctor to convert the text properly. However, you may notice that certain characters for certain languages, such as Chinese, are missing in the PDF. Read on to find out why and how to address it.

If you’re writing in a non-Latin language, you need to use a dedicated theme that provides the necessary fonts. For example, to produce a PDF from a document written in a CJK language such as Chinese, you need to use a CJK theme. You can get such a theme by installing the asciidoctor-pdf-cjk-kai_gen_gothic gem. See the asciidoctor-pdf-cjk-kai_gen_gothic project for detailed instructions.

Using a dedicated theme is necessary because PDF is a “bring your own font” kind of system. In other words, the font you provide must provide glyphs for all the characters. There’s no one font that supports all the worlds languages (though some, like Noto Serif, certainly come close). Even if there were such a font, bundling that font with the main gem would make the package enormous. It would also severely limit the style choices in the default theme, which targets Latin-based languages.

Therefore, we’re taking the strategy of creating separate dedicated theme gems that target each language family, such as CJK. The base theme for CJK languages is provided by the asciidoctro-pdf-cjk project and a concrete implementation provided by the asciidoctor-pdf-cjk-kai_gen_gothic project that’s based on the kai_gen_gothic font. Of course, you’re free to follow this model and create your own theme gem that uses fonts of your choice.