If a TrueType font (not an AFM font) is missing a character needed to render the document, such as a special symbol or emoji, 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. If the character isn’t found in the fallback font, it will mostly likely be replaced by a box (i.e., the notdef glyph), which is guaranteed if you’re using the bundled fallback font.
When defining the fallback font, you must specify all four variants (
The fallback font only gets used when the primary font is a TrueType or OpenType font (i.e., TTF, DFont, TTC, OTF).
Any glyph missing from an AFM font is simply replaced with the “not” glyph (
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).
font: catalog: Roboto: normal: roboto-normal.ttf italic: roboto-italic.ttf bold: roboto-bold.ttf bold_italic: roboto-bold_italic.ttf DroidSansFallback: droid-sans-fallback.ttf
Notice that we only declare the fallback font file once using a literal value. This ensures the font is defined for all four variants so it will be used regardless of which font style is active when it’s called on. This assignment is equivalent to the following:
DroidSansFallback: '*': droid-sans-fallback.ttf
The benefit of this syntax is that it allows you to use a separate font file for just one of the variants (e.g., bold).
Next, add the key name to the
fallbacks key under the
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:
font: catalog: Roboto: normal: roboto-normal.ttf italic: roboto-italic.ttf bold: roboto-bold.ttf bold_italic: roboto-bold_italic.ttf DroidSansFallback: droid-sans-fallback.ttf fallbacks: - DroidSansFallback
If you are using more than one fallback font, add additional lines to the
Of course, make sure you’ve configured your theme to use your custom font:
base: font-family: Roboto
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.
Here’s another example that shows how to use an alternative emoji font (Symbola):
extends: default-with-font-fallbacks font: catalog: merge: true Symbola: /path/to/symbola.ttf fallbacks: [ M+ 1p, Symbola ]
Now Asciidoctor PDF will look for the emoji in the Symbola font instead of the Noto Emoji font.