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 (
The names of the built-in fonts (for general-purpose text) are as follows:
|Font Name||Font Family|
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.
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).|
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
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
- 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
- Noto Emoji
A font of emojis used as a fallback font in the
- Noto Sans
A sans font that is used as the fallback font in the
default-sans-with-font-fallbackstheme. It can be styled as
The default themes refer to the bundled fonts using the
To learn how to use a custom font in your theme alongside or in place of built-in or bundled fonts, refer to Use Custom Fonts.
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 --theme default-with-font-fallbacks document.adoc
-a scripts=cjk option.
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.