Create a CJK Theme

If you’re writing in a CJK language such as Simplified Chinese, you’ll likely need to bring your own font by providing a custom theme. That’s because it’s not possible for Asciidoctor PDF to bundle the necessary fonts since they are too large. Fortunately, creating a theme to override the fonts requires very few steps, so you should be up and running with your own font in no time.

Obtain the TTF fonts

The first step in creating a CJK theme is to obtain the fonts. It’s important that the fonts are TTF since that’s the only font format Asciidoctor PDF (via ttfunk) supports reliably.

Unfortunately, good quality TTF fonts for CJK languages are hard to come by. We recommend starting with the Noto Sans Variable Fonts for CJK provided by the noto-cjk project (Noto Sans and Noto Sans Mono). Just make sure you download the TTF variant.

Once you have downloaded the fonts, place the files into the directory where you are going to create your theme. For the purpose of this guide, we’ll assume you are working with the following font files:

If you’d like to use different fonts, refer to the list of notable CJK fonts on Wikipedia. With that information, you can search for the TTF font on any font service. You can also find the Kai Gen Gothic fonts for CJK languages in TTF format on the releases page for the now deprecated asciidoctor-pdf-cjk-kai_gen_gothic project.

Create the theme file

Now that you’ve obtained the TTF font files, you can create a new theme to use them.

Create a theme file named cjk-theme.yml where you can override the fonts:

extends: default
font:
  catalog:
    merge: true
    Noto Sans CN: NotoSansCJKsc-VF.ttf
    Noto Sans Mono CN: NotoSansMonoCJKsc-VF.ttf
  fallbacks:
  - Noto Serif
base:
  text-align: left
  font-family: Noto Sans CN
codespan:
  font-family: Noto Sans Mono CN
kbd:
  font-family: $codespan-font-family
code:
  font-family: $codespan-font-family

This theme does several things:

  1. Registers the Noto Sans CN and Noto Sans Mono CN fonts in the font catalog provided by the default theme

  2. Sets the built-in Noto Serif font as the fallback font in cases when a glyph is not provided by the CJK font

  3. Configures Noto Sans CN as the base font, which is used for all variable-width text in the document

  4. Sets the default text alignment to left since text justification isn’t well-suited for CJK languages

  5. Configures Noto Sans Mono CN as the monospaced font, which is used for all monospaced text in the document

If you’re using different fonts for normal, bold, italic, and bold italic, you’ll need to configure them using separate keys. Refer to Extending the font catalog for details.

When using your own fonts, be sure to consult the Prepare a Custom Font to find recommended modifications.

You may also want to darken the font color since the Noto Sans SC font has a thin weight.

base:
  text-align: left
  font-color: #000000
  font-family: Noto Sans CN
heading:
  font-color: #000000

You may need to adjust the font color on other keys as well.

Load your theme

Now that you’ve created the theme, you can put it to use. Since the theme provides custom fonts, you’ll need to specify both the location of the theme file and the location of the fonts when calling Asciidoctor PDF.

Let’s assume that your theme is located in the themes directory relative to your document. Here’s how you specify the path to the theme and the fonts it uses:

$ asciidoctor-pdf -a scripts=cjk -a pdf-theme=./themes/cjk-theme.yml -a pdf-fontsdir=./themes document.adoc

The -a pdf-fontsdir option is important because it tells Asciidoctor PDF where to look for the fonts specified in the theme. Alternately, the theme could specify the location of these fonts using an absolute path. The scripts option enables CJK support within Asciidoctor, which allows lines to break anywhere instead of at word boundaries.

If you’ve followed the instructions correctly, you should see that there are few (if any) missing glyphs in your PDF document.