Skip to content

life888888/asciidoctor-pdf-cjk-ext

Repository files navigation

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 (□)

BeforePatch

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

AfterPatch

Overview

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).

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

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

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.

  1. Please place the downloaded jar file in the AsciidocFX/lib directory.

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
  1. 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
  1. Modify the PDF settings of AsciidocFX’s ASCIIDOCTOR

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

GUI mode modification

  1. Execute AsciidocFX

AsciidocFX PDF Settings

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.

  1. Click on the right side menu ‵Settings‵ ①

  2. Click on the top right menu ‵PDF Settings‵ ②

  3. Click the ‵Add‵ button ③

  4. 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

  1. (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

  2. 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",
  1. 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

  1. 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

  1. Please download asciidoctorj-pdf-2.3.0.jar to the asciidoctorj/lib directory

  2. 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

  1. 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

  1. 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
  1. Set up

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.

maven pdf default page

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

maven pdf default fonts

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.

maven pdf pdf ext notosans cjk page

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

maven pdf pdf ext notosans cjk fonts

Asciidoctor

  1. 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
  1. It is recommended to use asciidoctor-pdf 2.x

Please execute the following command

sudo gem install asciidoctor-pdf --pre
  1. 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

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)

  1. In the directory where the adoc file is located, create a subdirectory theme or other name.

  2. In subdirectory custom-theme, create custom-default-ext-notosans-cjk-tc-theme.yml.

  3. Modify custom-default-ext-notosans-cjk-tc-theme.yml , adjust the settings to be changed.

  4. 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 default vs custom 1

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

asciidoctorj default vs custom 2

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 © 2022 life888888. and the asciidoctor-pdf-cjk-ext Project.

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:

MIT License - Copyright (c) 2015 Rei

MIT License - Copyright © 2014-present OpenDevise Inc. and the Asciidoctor Project

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.