pandoc 转换 markdown 为 pdf

2022-03-09 tech linux 6 mins 1 图 2178 字

一、安装

sudo apt install \
  pandoc \
  texlive-latex-base \
  texlive-fonts-recommended \
  texlive-extra-utils \
  texlive-latex-extra \
  texlive-xetex

二、背景介绍

Pandoc 可以很方便地对不同 Markup 语言的文件进行格式转换，因此被誉为格式转换的「瑞士军刀」。使用 Pandoc 把 Markdown 文件转为 PDF 文件，实际上包含两个步骤：

第一步， Markdown 文件被转为 LaTeX 源文件。
第二步，调用系统的 pdflatex, xelatex 或者其他 TeX 命令，将 .tex 文件转换为最终的 PDF 文件。

Pandoc 默认使用的 pdflatex 命令无法处理 Unicode 字符，如果要把包含中文的Markdown 文件转为 PDF，在生成 PDF 的过程中会报错。我们需要使用 xelatex 来处理中文，并且需要使用 mainfont 选项指定支持中文的字体。

pandoc --pdf-engine=xelatex -V mainfont="XXX" test.md -o test.pdf

三、安装和查看本机上的中文字体

安装字体

apt-get install fontconfig xfonts-utils # 安装fc-cache
apt-get install ttf-mscorefonts-installer # 微软的TrueType 核心字库
apt-get install ttf-wqy-microhei  #文泉驿-微米黑
apt-get install ttf-wqy-zenhei  #文泉驿-正黑
apt-get install xfonts-wqy #文泉驿-点阵宋体

我是debian环境，字体位置，/usr/share/fonts

fc-list :lang=zh

四、转换pdf常用参数

–latex-engine=pdflatex/lualatex/xelatex

–latex-engine用来指定转换PDF格式时LaTeX引擎，默认情况下是pdflatex，但是由于pdflatex不支持中文，因此需要将引擎设置为xelatex

–template=FILE

使用FILE指定的文件作为输出文档的自定义模板。可将模板文件放置任意处，只是指定FILE时需要该FILE的路径。

–toc, –table-of-contents

使用该参数后，会在输出文档开头自动产生文件目录，对于输出格式是man, docbook, slidy, slideous, s5, docx 或者odt的文档，该参数不起任何作用。

–toc-depth=NUMBER

指定文件目录中包含的章节级别，默认NUMBER=3，表示一级标题、二级标题、三级标题都会被在目录中展示。

-V KEY[=VAL], –variable=KEY[:VAL]

当渲染standalone模式下文档时，设置模板变量KEY的值为VAL。pandoc会自动设置默认模板中的这些变量，因此该选项这通常在使用–template选项指定自定义模板时有用，如果没有指定VAL值，那么该KEY会被赋予值true。

-s, –standalone

转换输出文档时会自动加上合适的header和footer(例如standalone HTML, LaTeX, RTF).该选择在转换输出pdf，epub，epub3，fb2，docx，odt格式文件时会被自动设置，因此如果转换输出上述格式文件，则不用显示指定该选项。

-N, –number-sections

对于转换输出LaTeX, ConTeXt, HTML, EPUB格式文档时，对文中章节进行编号。默认情况下，文章的章节是不会被编号的。对于使用了class unnumbered 的章节肯定不会被标号，即使使用了–number-sections选项。

五、命令备忘

pandoc --pdf-engine=xelatex -V mainfont='WenQuanYi Zen Hei Mono' 1.md --template pm -o 2.pdf

我用了这个模版，对中文比较友好，将 pm-template.latex 文件拷贝到 /usr/share/pandoc/data/templates后直接使用。

这个模版需要做些调整，将字体设置的地方LiHei Pro，改为我本机存在的字体WenQuanYi Zen Hei Mono。

遇到个问题，中文无法换行。最后直接用这个模版解决了。

还有另一个模版Eisvogel也比较常用的。