AsciiDoc 导出为 PDF ，支持中文内容

2022-07-10

CJK = 乱码或豆腐块。

AsciiDoc 相关工具的安装配置，可参考在 macOS 中使用 AsciiDoc 。

AsciiDoc 的文档，除了生成为 HTML 外，很多时候还需要导出为 PDF 。

导出

使用 Homebrew 安装 asciidoctor ，会默认同时安装 asciidoctor-pdf 工具。

1
2
3
4


asciidoctor -b pdf \
  -r asciidoctor-diagram \
  -r asciidoctor-pdf \
  index.adoc

以上命令会生成 index.pdf 文件，图表内容也会同时生成。

中文问题

但是如果 AsciiDoc 文档中存在 CJK 字符，那么生成的 pdf 文件将会是一个个的小方框（豆腐块）。此时可以通过自定义 scheme 的方式解决。

下载 googlefonts/noto-cjk 中文字体，注意要选择 “TTF” - “Subset Variable Simplified Chinese (简体中文)” 下的两种字体，保存到 themes/fonts/ 目录下。

不出意外的话，两个字体的文件名为：

NotoSansCJKsc-VF.ttf 一般字体
NotoSansMonoCJKsc-VF.ttf 等宽字体

新建 themes/cjk-fonts.theme 文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


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

生成 pdf 的命令增加几个参数，改为：

1
2
3
4
5
6
7


asciidoctor -b pdf \
  -r asciidoctor-diagram \
  -r asciidoctor-pdf \
  -a scripts=cjk \
  -a pdf-theme=./themes/cjk-fonts.yml \
  -a pdf-fontsdir='./themes/fonts;GEM_FONTS_DIR' \
  index.adoc

豆腐块不见了。

补充

从网上搜索的结果，还有另一种解决方案： GitHub - Mogztter/asciidoctor-web-pdf: Convert AsciiDoc documents to PDF using web technologies ，即调用浏览器来生成 pdf 文件。个人感觉该方案比较重，所以没去验证。