asciidoctor-pdf-cjk-ext

The following English content is translated by Google, and the original Chinese content is at README_zh-tw.adoc.

Asciidoctor PDF CJK Ext is used to provide the theme and ttf files needed by Asciidoctor / AsciidoctorJ / AsciidocFX / Maven / Gradle to generate PDF containing CJK languages (Chinese, Japanese, Korean).

Before modification - Chinese cannot be displayed normally, characters will show like tofu char (□)

After modification - Chinese can be displayed normally, bold, italic, and italic bold are all available

Table of Contents

Overview
Quick Install
- Linux / MacOS
- Windows
Download Themes And Fonts Package
- Jar Format
- Zip Format
Usage
- AsciidocFX
- AsciidoctorJ
- Maven
- Asciidoctor
- Gradle
PDF apply Theme level
Examples Files
Contributing
- Requirements
- Build Step
Copyright
TODO
Changelog

Overview

Theme supports Asciidoctor PDF 1.x and Asciidoctor PDF 2.x.
Font contains Noto Sans CJK, Noto Sans Mono CJK, Noto Serif CJK.
Each Font contains 4 styles: Regular, Bold, Italic, BoldItalic. (Italic, BoldItalic is generated by Fontforge)
Provide two usage modes: jar file and directory mode.

Quick Install

You don’t need to download the project source or a single zip or jar.

Please read Usage Type first to decide what you want to install.

Please choose one of the following to install:

Linux / MacOS

Windows

Download Themes And Fonts Package

If you are using AsciidoctorJ, AsciidocFX, Maven, Gradle recommends using the Jar first.

If you are using Asciidoctor recommends using the Download Zip first.

Runtimes	Jar Format	Zip Format
Asciidoctor	❌	✅ Zip Format
AsciidoctorJ	✅ Jar Format	✅ Zip Format
AsciidocFX	✅ Jar Format	✅ Zip Format
Maven	✅ Jar Format	✅ Zip Format
Gradle	✅ Jar Format	✅ Zip Format

Jar Format

Please choose one of the downloads according to the font and language you want to use.

Language / Fonts	Sans	Sans Mono	serif
SC (Simplified Chinese)	pdf-ext-notosans-cjk-sc.jar	pdf-ext-notosansmono-cjk-sc.jar	pdf-ext-notoserif-cjk-sc.jar
TC (Traditional Chinese)	pdf-ext-notosans-cjk-tc.jar	pdf-ext-notosansmono-cjk-tc.jar	pdf-ext-notoserif-cjk-tc.jar
HK (Hong Kong)	pdf-ext-notosans-cjk-hk.jar	pdf-ext-notosansmono-cjk-hk.jar	pdf-ext-notoserif-cjk-hk.jar
JP (Japanese)	pdf-ext-notosans-cjk-jp.jar	pdf-ext-notosansmono-cjk-jp.jar	pdf-ext-notoserif-cjk-jp.jar
KR (Korean)	pdf-ext-notosans-cjk-kr.jar	pdf-ext-notosansmono-cjk-kr.jar	pdf-ext-notoserif-cjk-kr.jar

Zip Format

Please choose one of the downloads according to the font and language you want to use.

Language / Fonts	Sans	Sans Mono	serif
SC (Simplified Chinese)	notosans-cjk-sc.zip	notosansmono-cjk-sc.zip	notoserif-cjk-sc.zip
TC (Traditional Chinese)	notosans-cjk-tc.zip	notosansmono-cjk-tc.zip	notoserif-cjk-tc.zip
HK (Hong Kong)	notosans-cjk-hk.zip	notosansmono-cjk-hk.zip	notoserif-cjk-hk.zip
JP (Japanese)	notosans-cjk-jp.zip	notosansmono-cjk-jp.zip	notoserif-cjk-jp.zip
KR (Korean)	notosans-cjk-kr.zip	notosansmono-cjk-kr.zip	notoserif-cjk-kr.zip

Usage

AsciidocFX

Important

Please confirm the version of AsciidocFX first

AsciidocFX-1.7.4 does not supports PDF Converter ASCIIDOCTOR.

Please place the downloaded jar file in the AsciidocFX/lib directory.
- Download install-jar-to-libs-dir.sh

change install-jar-to-libs-dir.sh parameter tc to your language (jp, kr, sc, hk)

$ chmod u+x install-jar-to-libs-dir.sh
$ ./install-jar-to-libs-dir.sh tc
$ cp ~/libs/*.jar ~/TOOLS/AsciidocFX/lib

Modify AsciidocFX memory configuration

Why do I need to modify the AsciidocFX memory configuration?

If it is not modified, there may be insufficient memory error when applying Chinese pdf. Then no pdf will be produced.

AsciidocFX/log/asciidocfx.log

java.lang.OutOfMemoryError: Java heap space

Edit AsciidocFX/AscidocFX.vmoptions , find -Xmx756M and modify -Xmx1024M or more like -Xmx1536M . Then archive.

AsciidocFX/AsciidocFX.vmoptions

-Xmx1536M

Modify the PDF settings of AsciidocFX’s ASCIIDOCTOR

You can use GUI mode to modify or editor mode to modify.

GUI mode modification

Execute AsciidocFX

Important

Confirm that PDF Converter is currently selected as ASCIIDOCTOR

Please make sure that PDF Converter is currently selected as ASCIIDOCTOR. If PDF Converter is currently selected as FOP, you will not see the above setting screen.
AsciidocFX AsciidocFX-1.7.6+ PDF Converter default is ASCIIDOCTOR.
If the PDF Converter you want to use is FOP, please leave this document, because this document does not support PDF Converter is FOP.

Click on the right side menu ‵Settings‵ ①
Click on the top right menu ‵PDF Settings‵ ②
Click the ‵Add‵ button ③
Enter the corresponding ‵attribute‵ and ‵value‵ contents according to the form below ④

attribute	value
pdf-fontsdir	uri:classloader:/data/fonts;GEM_FONTS_DIR;
pdf-themesdir	uri:classloader:/data/themes
pdf-theme	default-ext-notosans-cjk-tc

pdf-theme: There are 3 sets of table styles for each corresponding font, corresponding to the language, for example, your language is tc

(a) Select Font (sans, sansmono, serif), assuming you want to use Noto Sans CJK
(b) Select the corresponding theme (default-ext-notosans-cjk-tc , default-notosans-cjk-tc , notosans-cjk-tc)
1. Click the Save button when finished ⑤

After saving, the AsciidocFX default will use the theme you set to wrap the PDF.

Modify the profile directly

(If you are using AsciidocFX 1.7.6+) ,
- If you have already started AsciidocFX, open asciidoctor_pdf.json in .AscidocFX-1.7.6 in your home directory
- If you just installed and haven’t started AsciidocFX yet, open asciidoctor_pdf.json in the conf subdirectory of your AsciidocFX installation directory
Add the following under attributes:

"pdf-themesdir": "uri:classloader:/data/themes",
"pdf-fontsdir": "uri:classloader:/data/fonts;GEM_FONTS_DIR;",
"pdf-theme": "default-ext-notosans-cjk-tc",

The modified content is as follows, then archive and start AsciidocFX

{
    "backend": "pdf",
    "jsPlatform": "Asciidoctorj",
    "safe": "unsafe",
    "header_footer": true,
    "converter": "ASCIIDOCTOR",
    "attributes": {
        "pdf-themesdir": "uri:classloader:/data/themes",
        "pdf-fontsdir": "uri:classloader:/data/fonts;GEM_FONTS_DIR;",
        "pdf-theme": "default-ext-notosans-cjk-tc",
        "showtitle": "true",
        "allow-uri-read": "true",
        "experimental": "true",
        "source-highlighter": "rouge",
        "imagesdir": "images",
        "icons": "font"
    }
}

pdf-theme: You can choose one of the following

default-ext-notosans-cjk-tc
default-notosans-cjk-tc
notosans-cjk-tc
default-ext-notosansmono-cjk-tc
default-notosansmono-cjk-tc
notosansmono-cjk-tc
default-ext-notoserif-cjk-tc
default-notoserif-cjk-tc
notoserif-cjk-tc

Change tc to your language (jp, kr, sc, hk).

AsciidoctorJ

Copy the downloaded jar to the asciidoctorj/lib directory

EX: pdf-ext-notosans-cjk-tc.jar, pdf-ext-notosansmono-cjk-tc.jar, pdf-ext-notoserif-cjk-tc.jar

Please download asciidoctorj-pdf-2.3.0.jar to the asciidoctorj/lib directory
Modify the content of asciidoctorj/bin/asciidoctorj
- Change the original asciidoctorj-pdf-1.6.2.jar to asciidoctorj-pdf-2.3.0.jar
- Added pdf-ext-notosans-cjk-tc.jar, pdf-ext-notosansmono-cjk-tc.jar, pdf-ext-notoserif-cjk-tc.jar

asciidoctorj

#CLASSPATH=$APP_HOME/lib/asciidoctorj-2.5.4-bin.jar:$APP_HOME/lib/asciidoctorj-2.5.4.jar:$APP_HOME/lib/asciidoctorj-api-2.5.4.jar:$APP_HOME/lib/asciidoctorj-epub3-1.5.1.jar:$APP_HOME/lib/asciidoctorj-diagram-2.2.3.jar:$APP_HOME/lib/asciidoctorj-diagram-ditaamini-1.0.3.jar:$APP_HOME/lib/asciidoctorj-diagram-plantuml-1.2022.5.jar:$APP_HOME/lib/asciidoctorj-pdf-1.6.2.jar:$APP_HOME/lib/asciidoctorj-revealjs-4.1.0.jar:$APP_HOME/lib/jruby-complete-9.3.4.0.jar:$APP_HOME/lib/jcommander-1.82.jar:$APP_HOME/lib/pdf-ext-kaigengothic-tw.jar:$APP_HOME/lib/pdf-ext-notosansmono-cjk-tc.jar:$APP_HOME/lib/pdf-ext-notosans-cjk-tc.jar:$APP_HOME/lib/pdf-ext-notoserif-cjk-tc.jar

CLASSPATH=$APP_HOME/lib/asciidoctorj-2.5.4-bin.jar:$APP_HOME/lib/asciidoctorj-2.5.4.jar:$APP_HOME/lib/asciidoctorj-api-2.5.4.jar:$APP_HOME/lib/asciidoctorj-epub3-1.5.1.jar:$APP_HOME/lib/asciidoctorj-diagram-2.2.3.jar:$APP_HOME/lib/asciidoctorj-diagram-ditaamini-1.0.3.jar:$APP_HOME/lib/asciidoctorj-diagram-plantuml-1.2022.5.jar:$APP_HOME/lib/asciidoctorj-pdf-2.3.0.jar:$APP_HOME/lib/asciidoctorj-revealjs-4.1.0.jar:$APP_HOME/lib/jruby-complete-9.3.4.0.jar:$APP_HOME/lib/jcommander-1.82.jar:$APP_HOME/lib/pdf-ext-notosansmono-cjk-tc.jar:$APP_HOME/lib/pdf-ext-notosans-cjk-tc.jar:$APP_HOME/lib/pdf-ext-notoserif-cjk-tc.jar

Important

Why use asciidoctorj-pdf-2.3.0.jar instead

Because asciidoctorj-pdf-2.x has modified some problems about accessing pdf-theme, pdf-fontsdir, it is recommended to use asciidoctorj-pdf-2.x first.

AsciidoctorJ usage example

asciidoctorj -b pdf \
  -a allow-uri-read \
  -a icons="font" \
  -a idprefix \
  -a idseparator="-" \
  -a imagesdir="images" \
  -a pagenums \
  -a toc \
  -a scripts="cjk" \
  -a pdf-fontsdir="uri:classloader:/data/fonts;GEM_FONTS_DIR;" \
  -a pdf-themesdir="uri:classloader:/data/themes" \
  -a pdf-theme="default-ext-notosans-cjk-tc" \
  PDF-CJK-TEST_TW.adoc

pdf-theme: You can choose one of the following

default-ext-notosans-cjk-tc
default-notosans-cjk-tc
notosans-cjk-tc
default-ext-notosansmono-cjk-tc
default-notosansmono-cjk-tc
notosansmono-cjk-tc
default-ext-notoserif-cjk-tc
default-notoserif-cjk-tc
notoserif-cjk-tc

Maven

Copy the downloaded jar to the asciidoctorj/lib directory

EX: pdf-ext-notosans-cjk-tc.jar, pdf-ext-notosansmono-cjk-tc.jar, pdf-ext-notoserif-cjk-tc.jar

Install the jar archive to your Maven Local Repo ( /home/demo/.m2)

Take the language tc as an example, execute the following command to install the jar file to your Local Maven Repo.

Important

IMPORTANT

Before executing the following command, the execution location should be in the directory where you downloaded the jar file.

mvn install:install-file \
  -Dfile=pdf-ext-notoserif-cjk-tc.jar \
  -DgroupId=com.life888888.lab \
  -DartifactId=pdf-ext-notoserif-cjk-tc \
  -Dversion=0.1.0 \
  -Dpackaging=jar


mvn install:install-file \
  -Dfile=pdf-ext-notosans-cjk-tc.jar \
  -DgroupId=com.life888888.lab \
  -DartifactId=pdf-ext-notosans-cjk-tc \
  -Dversion=0.1.0 \
  -Dpackaging=jar

mvn install:install-file \
  -Dfile=pdf-ext-notosansmono-cjk-tc.jar \
  -DgroupId=com.life888888.lab \
  -DartifactId=pdf-ext-notosansmono-cjk-tc \
  -Dversion=0.1.0 \
  -Dpackaging=jar

Set up

Take https://github.com/asciidoctor/asciidoctor-maven-examples/tree/main/asciidoctor-pdf-example as an example.

After downloading to this computer, first test to confirm that the project can run normally.

Execute the following commands.

cd asciidoctor-pdf-example

mvn

After the execution is complete, check whether target/generated-docs/example-manual.pdf is generated.

Open example-manual.pdf and check the font properties, make sure it is the default NotoSerif.

Next, modify pom.xml.

Find the build → plugins → plugin (asciidoctor-maven-plugin) paragraph

Add the following content under dependencies, you can add only one font and style to be added, for example: pdf-ext-notoserif-cjk-tc.

                        <dependency>
                           <groupId>com.life888888.lab</groupId>
                           <artifactId>pdf-ext-notoserif-cjk-tc</artifactId>
                           <version>0.1.0</version>
                       </dependency>
                       <dependency>
                           <groupId>com.life888888.lab</groupId>
                           <artifactId>pdf-ext-notosans-cjk-tc</artifactId>
                           <version>0.1.0</version>
                       </dependency>
                       <dependency>
                           <groupId>com.life888888.lab</groupId>
                           <artifactId>pdf-ext-notosansmono-cjk-tc</artifactId>
                           <version>0.1.0</version>
                       </dependency>

Then find execution (generate-pdf-doc) → configuration , add the following parameter settings under attributes.

           <attributes>
                 <pdf-fontsdir>uri:classloader:/data/fonts;GEM_FONTS_DIR;</pdf-fontsdir>
                 <pdf-themesdir>uri:classloader:/data/themes</pdf-themesdir>
                 <pdf-theme>default-ext-notosans-cjk-tc</pdf-theme>
                 ...

Execute the following command again.

cd asciidoctor-pdf-example

mvn clean generate-resources

After the execution is complete, check whether target/generated-docs/example-manual.pdf is generated.

Open example-manual.pdf and check the font property, confirm that it is already NotoSansCJKTC .

Asciidoctor

Please download the zip archive (EX: notoserif-cjk-tc.zip ), and unzip it. Suppose it is decompressed and placed in the /home/demo/Asciidoctor-PDF-CJK directory.

.
├── fonts
│   ├── LICENSE
│   ├── notoserif-cjk-tc-bold_italic.ttf
│   ├── notoserif-cjk-tc-bold.ttf
│   ├── notoserif-cjk-tc-italic.ttf
│   └── notoserif-cjk-tc-normal.ttf
└── themes
    ├── default-ext-notoserif-cjk-tc-pdf-1-theme.yml
    ├── default-ext-notoserif-cjk-tc-theme.yml
    ├── default-notoserif-cjk-tc-pdf-1-theme.yml
    ├── default-notoserif-cjk-tc-theme.yml
    ├── LICENSE
    ├── LICENSE-asciidoctor-pdf
    ├── LICENSE-asciidoctor-pdf-cjk-kai_gen_gothic
    ├── notoserif-cjk-tc-pdf-1-theme.yml
    └── notoserif-cjk-tc-theme.yml

It is recommended to use asciidoctor-pdf 2.x

Please execute the following command

sudo gem install asciidoctor-pdf --pre

Asciidcotor usage example

asciidoctor \
  -b pdf \
  -a scripts="cjk" \
  -a allow-uri-read \
  -a icons="font" \
  -a idprefix \
  -a idseparator="-" \
  -a imagesdir="images" \
  -a pagenums \
  -a toc \
  -a pdf-theme="default-notoserif-cjk-tc" \
  -a pdf-themesdir="/home/demo/Asciidoctor-PDF-CJK/themes" \
  -a pdf-fontsdir="/home/demo/Asciidoctor-PDF-CJK/fonts;GEM_FONTS_DIR;" \
  PDF-CJK-TEST_TW.adoc

pdf-theme can use default-notoserif-cjk-tc (if pdf-themesdir is set) or /home/demo/Asciidoctor-PDF-CJK/themes/default-notoserif-cjk-tc-theme.yml.

Gradle

Please reference https://github.com/life888888/asciidoctor-pdf-cjk-ext-gradle-examples

It contains various usage examples of using Asciidoctor Gradle Plugin with asciidoctor-pdf-cjk-ext theme.

Contains examples of using Custom Theme.

PDF apply Theme level

AscidocFX Level

AscidocFX will use the set default set when applying the PDF. Asciidoc files (.adoc) do not need to set pdf-fontsdir, pdf-themesdir, pdf-theme.

Single Adoc File Level - Use Installed Jar (Fonts And Themes)

If only one adoc file (EX: AAA.adoc) wants to apply a different Theme, you can do this:

Add pdf-fontsdir,pdf-themesdir,pdf-theme settings directly in the AAA.adoc file header.

:pdf-theme: default-notoserif-cjk-tc

Single Adoc File Level - Use Custom Themes

If only a certain adoc file (EX: AAA.adoc) wants to change theme settings that are different from the one already installed, such as font color, you can do:

(You don’t need to modify the theme file inside the Installed Jar)

In the directory where the adoc file is located, create a subdirectory theme or other name.
In subdirectory custom-theme, create custom-default-ext-notosans-cjk-tc-theme.yml.
Modify custom-default-ext-notosans-cjk-tc-theme.yml , adjust the settings to be changed.
In the AAA.adoc file header, change pdf-themesdir, pdf-theme settings to point to custom theme folder.

:pdf-themesdir: {docdir}/theme
:pdf-theme: custom-default-ext-notosans-cjk-tc

Extended Custom Theme

.
├── PDF-CJK-TEST_TW.adoc
└── theme
    ├── cover.png
    └── custom-default-ext-notosans-cjk-tc-theme.yml

custom-default-ext-notosans-cjk-tc-theme.yml

extends:
  - default-ext-notosans-cjk-tc
title-page:
  align: left
  logo:
    image: image:{docdir}/theme/cover.png[align=center]
    top: 0%
page:
  margin: [0.75in, 1in, 0.75in, 1in]
base:
  line-height-length: 20
heading:
  font-color: #FF8000
  font-size: 12
  line-height: 1.2
link:
  font-color: #009900
header:
  height: 0.75in
  line-height: 1
  recto:
    right:
      content: '{document-title}'
  verso:
    left:
      content: '{document-title}'
footer:
  height: 0.75in
  line-height: 1
  recto:
    right:
      content: '{chapter-title} | *{page-number}*'
  verso:
    left:
      content: '*{page-number}* | {chapter-title}'
image:
  align: center
caption:
  align: center
  font-color: #FF0000
  font-size: 10

The following uses AsciidoctorJ as an example to list the modified parameters in the following:

asciidoctorj -b pdf \
  -a allow-uri-read \
  -a icons="font" \
  -a idprefix \
  -a idseparator="-" \
  -a imagesdir="images" \
  -a pagenums \
  -a toc \
  -a scripts="cjk" \
  -a pdf-fontsdir="uri:classloader:/data/fonts;GEM_FONTS_DIR;" \
  -a pdf-themesdir="uri:classloader:/data/themes" \
  -a pdf-theme="/home/demo/Documents/TestAsciidoc/theme/custom-default-ext-notosans-cjk-tc-theme.yml" \
  -o PDF-CJK-TEST_TW-custom-default-ext-notosans-cjk-tc-theme.pdf \
  PDF-CJK-TEST_TW.adoc

Different PDF-CJK-TEST_EN.pdf vs PDF-CJK-TEST_EN-custom-default-ext-notosans-cjk-tc-theme.pdf

theme: default-ext-notosans-cjk-tc vs custom-default-ext-notosans-cjk-tc

asciidoctorj -b pdf \
  -a doctype=book \
  -a allow-uri-read \
  -a icons="font" \
  -a idprefix \
  -a idseparator="-" \
  -a imagesdir="images" \
  -a pagenums \
  -a toc \
  -a scripts="cjk" \
  -a pdf-fontsdir="uri:classloader:/data/fonts;GEM_FONTS_DIR;" \
  -a pdf-themesdir="uri:classloader:/data/themes" \
  -a pdf-theme="default-ext-notosans-cjk-tc" \
  -o PDF-CJK-TEST_TW_BOOK.pdf \
  PDF-CJK-TEST_TW.adoc

asciidoctorj -b pdf \
  -a doctype=book \
  -a allow-uri-read \
  -a icons="font" \
  -a idprefix \
  -a idseparator="-" \
  -a imagesdir="images" \
  -a pagenums \
  -a toc \
  -a scripts="cjk" \
  -a pdf-fontsdir="uri:classloader:/data/fonts;GEM_FONTS_DIR;" \
  -a pdf-themesdir="uri:classloader:/data/themes" \
  -a pdf-theme="/home/demo/Documents/TestAsciidoc/theme/custom-default-ext-notosans-cjk-tc-theme.yml" \
  -o PDF-CJK-TEST_TW_BOOK-custom-default-ext-notosans-cjk-tc-theme.pdf \
  PDF-CJK-TEST_TW.adoc

doctype=book, theme: default-ext-notosans-cjk-tc vs custom-default-ext-notosans-cjk-tc

Examples Files

Attach the Examples file for testing in the examples directory.

Contains Custom Theme.

Contributing

You can re-generate jar and zip files, please refer to the following settings:

Requirements

OS: Ubuntu 20.04 or Other Linux
JDK: JDK 8+, only for jar command to package jar files.

Build Step

Download this project Source Code.

Unzip Project and enter the folder

$ unzip asciidoctor-pdf-cjk-ext.zip

$ cd asciidoctor-pdf-cjk-ext

Execute build-themes-all.sh

Edit build-themes-all.sh

./build-themes-all.sh

Example 1. You can build theme by font and language setting.

Edit build-themes-all.sh

# * Noto Sans CJK
# * Noto Sans Mono CJK
# * Noto Serif CJK
export BUILD_FONT_FS_SANS=1
export BUILD_FONT_FS_SANSMONO=1
export BUILD_FONT_FS_SERIF=1

# Languages: 1 = Build , 0 = None
# * SC (Simplified Chinese)
# * TC (Traditional Chinese)
# * HK (Hong Kong)
# * JP (Japanese)
# * KR (Korean)
export BUILD_FONT_LANG_SC=0
export BUILD_FONT_LANG_TC=1
export BUILD_FONT_LANG_HK=0
export BUILD_FONT_LANG_JP=0
export BUILD_FONT_LANG_KR=0

You can find the creted file in releases folder , include jar, zip files.

Copyright

Fonts License

Free use of this project fonts is granted under the terms of the SIL Open Font License.

Fonts License: cjk-fonts-ttf fonts - SIL Open Font License.

Code License

Free use of this project software is granted under the terms of the MIT License.

Third Party Theme License

My theme is modify from Two Projects:

Asciidoctor::Pdf::CJK::KaiGenGothic https://github.com/chloerei/asciidoctor-pdf-cjk-kai_gen_gothic

Asciidoctor PDF: A native PDF converter for AsciiDoc https://github.com/asciidoctor/asciidoctor-pdf

TODO

Examples files (Maven) and detailed instruction files will be sorted out.

Changelog

Refer to the CHANGELOG for a complete list of changes in older releases.