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. According to the section “Standard Type 1 Fonts” in the PDF specification, “these fonts, or their font metrics and suitable substitution fonts, shall be available to the conforming reader.”
You can use an AFM font anywhere a font-family key is recognized in the theme file.
For example:
base:
font-family: Times-RomanHowever, 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). |
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, andbold_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, orbold_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 thedefault-with-font-fallbackstheme. - Noto Emoji
-
A font of emojis used as a fallback font in the
default-with-font-fallbackstheme. - Noto Sans
-
A sans font that is used as the fallback font in the
default-sans-with-font-fallbackstheme. It can be styled asnormal,italic,bold, orbold_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).
|
Custom Fonts
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.
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 --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.
When using a CJK language, you probably don’t want text justification either, which is the default behavior.
You can overridde this setting using the text-align document attribute (or a custom theme).
$ asciidoctor-pdf -a scripts=cjk -a text-align=left --theme default-with-font-fallbacks document.adoc
If the built-in theme with the fallback font doesn’t go far enough, you’ll need to create a custom CJK theme.