Creating PDFs for non-latin languages and extra fonts

How to use custom fonts when creating PDFs from the IDE.


When creating a PDF from the IDE, the embedded Asciidoctor PDF needs true type fonts (TTFs) that include the characters included in the AsciiDoc source. Once the setup is complete, the user can choose Create PDF from current file from the editor’s action toolbar to convert the file.

Setup for Chinese fonts

Follow these steps to prepare an AsciiDoc file to be rendered as PDF with Chinese characters. A complete example is available in @ahus1’s AsciiDoc deep dive collection.

  1. Add a header to the document to specify folders and configurations:

    = 标题
    :pdf-themesdir: themes (1)
    :pdf-theme: zh_CN (2)
    :pdf-fontsdir: fonts (3)
    This is a show case for Chinese letters in AsciiDocs.
    1 Folder name with a theme file
    2 Name of the theme
    3 Folder with fonts referenced in theme
  2. Create a theme file zh_CN-theme.yml in folder themes:

    # default theme at
    extends: default
        - kaigen-gothic-cn
        # These are the KaiGen Gothic CN fonts, download them from
          normal: KaiGenGothicCN-Regular.ttf
          bold: KaiGenGothicCN-Bold.ttf
          italic: KaiGenGothicCN-Regular.ttf
          bold_italic: KaiGenGothicCN-Bold.ttf
        Noto Serif:
          normal: GEM_FONTS_DIR/notoserif-regular-subset.ttf
          bold: GEM_FONTS_DIR/notoserif-bold-subset.ttf
          italic: GEM_FONTS_DIR/notoserif-italic-subset.ttf
          bold_italic: GEM_FONTS_DIR/notoserif-bold_italic-subset.ttf
        # M+ 1mn supports ASCII and the circled numbers used for conums
        M+ 1mn:
          normal: GEM_FONTS_DIR/mplus1mn-regular-subset.ttf
          bold: GEM_FONTS_DIR/mplus1mn-bold-subset.ttf
          italic: GEM_FONTS_DIR/mplus1mn-italic-subset.ttf
          bold_italic: GEM_FONTS_DIR/mplus1mn-bold_italic-subset.ttf
      font_family: kaigen-gothic-cn
  3. Populate the fonts folder with KaiGenGothicCN*.ttf files downloaded from

Once the setup is complete, the user can use the Create PDF from current file from the editor’s action toolbar to convert the file.

Setup for Japanese, Korean and Taiwanese fonts

Follow the instructions above and use the fonts available in @minjiex’s kaigen-gothic repository or other TTF fonts.

Advanced Features

When using a multi-file document, users want to avoid putting the PDF attributes in each file, but still want to be able to create PDF previews from each file.

A solution to this is an .asciidoctorconfig file that contains the attributes. The AsciiDoc plugin will apply the attributes in this file to each file in that folder and the folders beneath it. A typical file would look like this:

:pdf-fontsdir: {asciidoctorconfigdir}/fonts
:pdf-themesdir: {asciidoctorconfigdir}/themes
:pdf-theme: zh_CN

Read more about this feature in the chapter Asciidoctor Config File.

Further reading

Public examples

There is @diguage’s “JDK source code analysis” document available. It contains AsciiDoc in Chinese plus a working setup for an .asciidoctorconfig file. As fonts, the author has chosen Source Han Serif and converted them to TTF. Download the fonts in cfg/fonts first to make it work.

pdf with chinese characters preview