Fonts

You can select from built-in fonts, fonts bundled with Asciidoctor PDF, or custom fonts loaded from TrueType (TTF) or OpenType (OTF) font files. If you want to use custom fonts, you must first declare them in your theme file.

Asciidoctor has no challenge working with Unicode. In fact, it prefers Unicode and considers the entire range. However, once you convert to PDF, you have to meet the font requirements of PDF in order to preserve Unicode characters. That means you need to provide a font (at least a fallback font) that contains glyphs for all the characters you want to use. If you don’t, you may notice that characters are missing (usually replaced with a box). There’s nothing Asciidoctor can do to convince PDF to work with extended characters without the right fonts in play. To see which characters are missing from the font, enable verbose mode (-v) when running Asciidoctor PDF.

Built-In (AFM) fonts

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

Font Name Font Family

Helvetica

sans-serif

Times-Roman

serif

Courier

monospace

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:

base:
  font-family: Times-Roman

However, when you use a built-in font, the characters you can use in your document are limited to the characters in the WINANSI (Windows-1252) code set. 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.

Built-in (AFM) fonts do not use the fallback fonts. In order for the fallback font to kick in, you must use a TrueType font anywhere you want the fallback font to be used (e.g., the base font family, the code font family, etc).
WINANSI Encoding Behavior

When using the built-in PDF (AFM) fonts on a block of content in your AsciiDoc document, any character that cannot be encoded to WINANSI is replaced with a logic “not” glyph (¬) and you’ll see the following warning in your console:

The following text could not be fully converted to the Windows-1252 character set:
| <string with unknown glyph>

This behavior differs from the default behavior in Prawn, which is to simply crash.

You’ll often see this warning if you’re using callouts in your document and you haven’t specified a TrueType font in your theme. To prevent this warning, you need to specify a TrueType font.

When using a TrueType font, you will get no warning for a missing glyph. That’s a consequence of how Prawn works and is outside of Asciidoctor PDF’s control. However, you’ll likely see it substituted with a box (guaranteed if you’re using one of the bundled fonts).

For more information about how Prawn handles character encodings for built-in fonts, see this note in the Prawn CHANGELOG.

Bundled fonts

Asciidoctor PDF bundles several fonts that are used by the default theme or a fallback font theme that extends the default theme. You can also declare these fonts in your custom theme. 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 names of the fonts bundled with Asciidoctor PDF are as follows:

M+ 1mn

A monospaced font that maps different thicknesses to the styles normal, italic, bold, and bold_italic. M+ 1mn also provides the circled numbers used for callouts and callout lists.

Noto Serif

A serif font that can be styled as normal, italic, bold, or bold_italic.

M+ 1p

A sans-serif font that provides a very complete set of Unicode glyphs. M+ 1p can only be styled as normal. This font is used as the fallback font in the default-with-font-fallbacks theme.

Noto Emoji

A font of emojis used as a fallback font in the default-with-font-fallbacks theme.

Noto Sans

A sans font that is used as the fallback font in the default-sans-with-font-fallbacks theme. It can be styled as normal, italic, bold, or bold_italic.

The default themes refer to the bundled fonts using the GEM_FONTS_DIR prefix. That means you can extend a default theme and not have to worry about how the bundled fonts get resolved. If you redeclare the bundled fonts in your custom theme, be sure to prefix the path with the GEM_FONTS_DIR token. An alternative approach is to include GEM_FONT_DIR in the value of the pdf-fontsdir attribute separated by the location of your custom fonts using a comma (e.g., path/to/your/fonts,GEM_FONTS_DIR) or a semicolon (e.g., path/to/your/fonts;GEM_FONTS_DIR).

Support for non-Latin languages

Asciidoctor PDF 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 (that’s important!), and expect Asciidoctor PDF to convert the text properly. But you still need a font that provides the glyphs for those characters.

When converting a document with Asciidoctor PDF, you may notice that some glyphs for certain languages, such as Simplified Chinese, are missing from the PDF. PDF is a “bring your own font” kind of system. In other words, the font you provide must provide glyphs for all the characters used. There’s no single font that supports all the world’s languages (though some, like Noto Sans and Noto Serif, certainly come close). Even if there were such a font, bundling that font with the main gem would make it enormous. It would also severely limit the style choices in the default theme, which caters to Latin-based languages.

If you’re writing in a CJK language, such as Japanese, Asciidoctor PDF provides a built-in theme named default-with-font-fallbacks that provides a broad range of characters in the CJK charsets. You can start with that theme to see how far it gets you:

$ asciidoctor-pdf -a scripts=cjk -a pdf-theme=default-with-font-fallbacks document.adoc

Notice the -a scripts=cjk option. That’s important. It tells the converter to insert break opportunities between CJK characters so that lines wrap properly when mixing English and a CJK language like Japanese.

If the built-in theme with the fallback font doesn’t go far enough, you’ll need to create a custom CJK theme.