Fallback Fonts

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 (normal, bold, italic, bold_italic), even if you use the same font file for each.
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 (¬).
The default theme does not use a fallback font. However, the built-in default-with-font-fallbacks theme does. In fact, it provides two. One for general writing in non-Latin languages (M+ 1p) and another for emoji (Noto Emoji). Using the fallback font slows down PDF generation slightly because it has to analyze every single character. Its use is not recommended for large documents. Instead, it’s best to select primary fonts that have all the characters you need.

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 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:

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 fallbacks key.

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.