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.

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

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:

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:

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

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

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

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

This command is just a shorthand way of running:

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.

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.

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.

Like CSS, inheritance is a principle feature in the Asciidoctor PDF theme language. For many of the properties, if a key is not specified, the key inherits the value applied to the parent content in the content hierarchy. This behavior saves you from having to specify properties unless you want to override the inherited value.

The following keys are inherited:

To save you from having to type the same value in your theme over and over, or to allow you to base one value on another, the theme language supports variables. Variables consist of the key name preceded by a dollar sign ($) (e.g., $base_font_size). Any qualified key that has already been defined can be referenced in the value of another key. (In order words, as soon as the key is assigned, it’s available to be used as a variable).

For example, once the following line is processed,

the variable $base_font_color will be available for use in subsequent lines and will resolve to #333333. Let’s say you want to make the font color of the sidebar title the same as the heading font color. Just assign the value $heading_font_color to the $sidebar_title_font_color.

You can also use variables in math expressions to use one value to build another. This is commonly done to set font sizes proportionally.It also makes it easy to test different values very quickly.

We’ll cover more about math expressions later.

The theme language supports basic math operations to support calculated values. Like programming languages, multiple and divide take precedence over add and subtract.

The following table lists the supported operations and the corresponding operator for each.

Here’s an example of a math expression with fixed values.

Variables may be used in place of numbers anywhere in the expression:

Values used in a math expression are automatically coerced to a float value before the operation. If the result of the expression is an integer, the value is coerced to an integer afterwards.

The theme language also supports several functions for rounding the result of a math expression. The following functions may be used if they surround the whole value or expression for a key.

You might use these functions in font size calculations so that you get more exact values.

Several of the keys require a value in points (pt), the unit of measure for the PDF canvas. A point is defined as 1/72 of an inch. If you specify a number without any units, the units defaults to pt.

However, us humans like to think in real world units like inches (in), centimeters (cm), or millimeters (mm). You can let the theme do this conversion for you automatically by adding a unit notation next to any number.

The following units are supported:

A percentage with the % unit is calculated relative to the width or height of the content area. Viewport-relative percentages (vw or vh units) are calculated as a percentage of the page width or height, respectively. Currently, percentage units can only be used for placing elements on the title page or for setting the width of a block image.

Here’s an example of how you can use inches to define the page margins:

The order of elements in a measurement array is the same as it is in CSS:

The align subkey is used to align text and images within the parent container.

In most cases, whereever you can specify a custom font family, you can also specify a font style. These two settings are combined to locate the font to # use.

The following font styles are recognized:

Many places where font properties can be specified, a case transformation can be applied to the text. The following transforms are recognized:

The theme language supports color values in three formats:

An image is specified either as a bare image path or as an inline image macro as found in the AsciiDoc syntax. Images are currently resolved relative to the value of the pdf-stylesdir attribute.

The following image types (and corresponding file extensions) are supported:

Here’s how an image is specified in the theme file as a bare image path:

Here’s how the image is specified using the inline image macro:

Like in the AsciiDoc syntax, the inline image macro allows you to supply set the width of the image and the alignment:

Some of the keys accept a quoted string as text content. The final segment of these keys is always named content.

A content key accepts a string value. It’s usually best to quote the string or use the YAML multi-line string syntax.

Text content may be formatted using a subset of inline HTML. You can use the well-known elements such as <strong>, <em>, <code>, <a>, <sub>, <sup>, <del>, and <span>. The <span> element supports the style attribute, which you can use to specify the color, font-weight, and font-style CSS properties. You can also use the rgb attribute on the <color> element to change the color or the name and size attributes on the <font> element to change the font properties. If you need to add an underline or strikethrough decoration to the text, you can assign the underline or line-through to the class attribute on any aforementioned element.

Here’s an example of using formatting in the content of the menu caret:

Additionally, normal substitutions are applied to the value of content keys for running content, so you can use most AsciiDoc inline formatting (e.g., *strong* or {attribute-name}) in the values of those keys.

The names of the built-in fonts (for general-purpose text) are as follows:

Using a built-in font requires no additional files. You can use the key anywhere a font_family property is accepted in the theme file. For example:

However, when you use a built-in font, the characters you can use in your document are limited to the characters in the WINANSI code set (Windows-1252). WINANSI includes most of the characters needed for writing in Western languages (English, French, Spanish, etc). For anything outside of that, PDF is BYOF (Bring Your Own Font).

Even though the built-in fonts require the content to be encoded in WINANSI, you still type your AsciiDoc document in UTF-8. Asciidoctor PDF encodes the content into WINANSI when building the PDF.

Asciidoctor PDF bundles several fonts that are used by the default theme. You can also use these fonts in your custom theme by simply declaring them. These fonts provide more characters than the built-in PDF fonts, but still only a subset of UTF-8 (to reduce the size of the gem).

The family name of the fonts bundled with Asciidoctor PDF are as follows:

The limited character set of WINANSI, or the bland look of the built-in fonts, may motivate you to load your own font. Custom fonts can enhance the look of your PDF theme substantially.

To start, you need to find a collection of TTF file of the font you want to use. A collection typically consists of all four styles of a font:

You’ll need all four styles to support AsciiDoc content properly. Asciidoctor PDF cannot italicize a font dynamically like a browser can, so you need the italic style.

Once you’ve obtained the TTF files, put them into a directory in your project where you want to store the fonts. It’s recommended that you name them consistently so it’s easier to type the names in the theme file.

Let’s assume the name of the font is Roboto. Name the files as follows:

Next, declare the font under the font_catalog key at the top of your theme file, giving it a unique key (e.g., Roboto).

You can use the key that you assign to the font in the font catalog anywhere the font_family property is accepted in the theme file. For instance, to use the Roboto font for all headings, you’d use:

When you execute Asciidoctor PDF, you need to specify the directory where the fonts reside using the pdf-fontsdir attribute:

When Asciidoctor PDF creates the PDF, it only embeds the glyphs from the font that are needed to render the characters present in the document. In other words, Asciidoctor PDF automatically subsets the font. However, if you’re storing the fonts in a repository, you may want to subset the font (for instance, by using FontForge) to reduce the space the font occupies in that storage. This is simply a personal preference.

You can add any number of fonts to the catalog. Each font must be assigned a unique key, as shown here:

If a TrueType font is missing a character needed to render the document, such as a special symbol, you can have Asciidoctor PDF look for the character in a fallback font. You only need to specify a single fallback font, typically one that provides a full set of symbols.

Like with other custom fonts, you first need to declare the fallback font. Let’s choose Droid Sans Fallback. You can map all the styles to a single font file (since bold and italic don’t usually make sense for symbols).

Next, add the key name to the fallbacks key under the font_catalog key. The fallbacks key accepts an array of values, meaning you can specify more than one fallback font. However, we recommend using a single fallback font, if possible, as shown here:

Of course, make sure you’ve configured your theme to use your custom font:

That’s it! Now you’re covered. If your custom font is missing a glyph, Asciidoctor PDF will look in your fallback font. You don’t need to reference the fallback font anywhere else in your theme file.