Creating PDFs for non-latin languages and extra fonts

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

Situation

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: {docdir}/themes (1)
:pdf-theme: zh_CN (2)
:pdf-fontsdir: {docdir}/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:

    themes/zh_CN-theme.yml
    # default theme at https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/themes/default-theme.yml
extends: default
font:
  fallbacks:
    - kaigen-gothic-cn
  catalog:
    # These are the KaiGen Gothic CN fonts, download them from
    # https://github.com/minjiex/kaigen-gothic/tree/master/dist/CN
    kaigen-gothic-cn:
      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
base:
  font_family: kaigen-gothic-cn

  3. Populate the fonts folder with KaiGenGothicCN*.ttf files downloaded from https://github.com/minjiex/kaigen-gothic/tree/master/dist/CN

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:

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

Find more documentation reading the chapter “Support for Non-Latin Languages” in Asciidoctor PDF’s documentation.

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