使用 Pandoc 来转换 Markdown 为漂亮的 PDF 格式

安装好 Pandoc

详细可以参考 Pandoc - Installing pandoc。

官网上给出的简单的不修改格式的将 Markdown 转换为 PDF 命令如下：

pandoc -f markdown -t html -o index.pdf

或者通过官方提供的 Docker 镜像来免于安装的环境的烦恼。

docker run --rm -v "$(pwd):/data" pandoc/latex -f markdown -t html -o index.pdf

为了简化，后续的流程在镜像中进行 alias pandoc='docker run --rm -v "$(pwd):/data" pandoc/latex'。

自定义样式

参考 Converting Markdown to Beautiful PDF with Pandoc - jdhao’s blog 增加一些自定义的配置之后。

由于 Pandoc 官方提供的 pandoc/latex 镜像有些 latex 包不完整，所以在其基础上，增加了一些 Latex 安装包，制作出新的镜像 5200710/pandoc-latex:latest。

FROM pandoc/latex
RUN tlmgr install quoting || exit 1

1. 指定中文字体

由于默认的 latex 镜像中不包含中文字体，需要自己手动安装和选择。

fc-list :lang=zh

从列表中找到自己的所选择的字体类型。或者从相关的 fonts 的网站中找到相关的字体文件。

pandoc --latex-engine=xelatex -V mainfont='WenQuanYi Micro Hei' test.md -o test.pdf

2. 更改 PDF 的 margin

pandoc --pdf-engine=xelatex -V geometry:"top=2cm, bottom=1.5cm, left=2cm,
right=2cm" -o test.pdf test.md

3. 为inline code 增加背景色

% change background color for inline code in
% markdown files. The following code does not work well for
% long text as the text will exceed the page boundary
\definecolor{bgcolor}{HTML}{E0E0E0}
\let\oldtexttt\texttt

\renewcommand{\texttt}[1]{
  \colorbox{bgcolor}{\oldtexttt{#1}}
}	

输出文件

构建好之后运行如下的命令：

docker run --rm -v "$(pwd):/data" -v "$HOME/fonts":"/usr/share/fonts" \
  5200710/pandoc-latex:latest \
  -f markdown /data/Spark\ 学习记录.md --pdf-engine=xelatex --toc \
  --highlight-style tango \
  -V colorlinks -V urlcolor=NavyBlue -V toccolor=NavyBlue \
  -H head.tex \
  -V 'mainfont:PingFang SC' -s -o index.pdf

我们来逐步的解释下上面的命令

1. Docker 命令细节不做过多解释，其中 -v "$HOME/fonts":"/usr/share/fonts" 挂在了本地的 PingFang SC 字体到容器中，用于能够指定对应的字体；
2. -f markdown 表明输入的文件格式；
3. --pdf-engine=xelatex 表示采用的 PDF 渲染引擎；
4. --highlight-style tango 表明采用了那种代码高亮的模板。因为是 PDF 所以才用了只有一点灰度的底色方案；
5. -V colorlinks -V urlcolor=NavyBlue -V toccolor=NavyBlue 等表明一些链接的配置，默认是没有颜色；
6. -H head.tex 可以把一些复杂的配置，写到 head.tex 文件中，然后应用。

这里给出一份 head.tex 参考方案。

\usepackage[top=2cm, bottom=1.5cm, left=2cm, right=2cm]{geometry}
% change background color for inline code in
% markdown files. The following code does not work well for
% long text as the text will exceed the page boundary
\definecolor{bgcolor}{HTML}{E0E0E0}
\let\oldtexttt\texttt

\renewcommand{\texttt}[1]{
    \colorbox{bgcolor}{\oldtexttt{#1}}
}

% Change the default style of block quote

\usepackage{framed}
\usepackage{quoting}

\definecolor{bgcolor}{HTML}{DADADA}
\colorlet{shadecolor}{bgcolor}
% define a new environment shadedquotation. You can change leftmargin and
% rightmargin as you wish.
\newenvironment{shadedquotation}
{\begin{shaded*}
     \quoting[leftmargin=1em, rightmargin=0pt, vskip=0pt, font=itshape]
     }
     {\endquoting
\end{shaded*}
}

%
\def\quote{\shadedquotation}
\def\endquote{\endshadedquotation}

更多的 latex 变量参考链接 Pandoc - Pandoc User’s Guide。

效果

实际渲染的效果还是不错的，渲染后的 PDF 文件如下。

错误

错误1: LaTex 提示找不到相关的依赖包

Error producing PDF.
! LaTeX Error: File `quoting.sty' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: sty)

Enter file name: 
! Emergency stop.
<read *> 

提示缺少相关的 quoting 包

1. 自动安装，利用 latex 的 Package 管理工具来安装。简单高效。

   tlmgr install quoting
   

2. 手动安装

   1. 前往 CTAN 官网搜素对应的安装包

   2. 下载 安装包之后解压

   3. 进入解压目录下，利用latex命令， 将 .inc 和 .dtx 后缀文件编译为 .sty 文件。

      latex quoting.ins
      

   4. 利用 kpsewhich -var-value TEXMFLOCAL 命令查找系统安装包的路径

      ➜  ~ kpsewhich -var-value TEXMFLOCAL
      /usr/local/texlive/2021basic/texmf-local
      

   5. 将前面的生成的 quoting.dtx 文件，复制到系统安装包的同级 texmf-dist 路径上，如: /usr/local/texlive/2021basic/texmf-dist/tex/latex/quoting 目录下。

   6. 运行 mktexlsr 刷新新增包的状态。一定要运行，否则手动安装的包不生效。

错误2: LaTex 提示找不到相关的字体

在转换为PDF的时候，如果输入的是中文，默认不支持，需要手动的指定fonts。

➜  ~ fc-list :lang=zh | grep PingFang
/System/Library/Fonts/PingFang.ttc: PingFang TC,蘋方\-繁,苹方\-繁:style=Regular,標準體,常规体
/System/Library/Fonts/PingFang.ttc: PingFang SC,蘋方\-簡,苹方\-简:style=Regular,標準體,常规体

可以查看系统中安装了哪些中文字体。比如：我系统安装了 PingFang SC 的字体。

错误3：转换 HTML 格式为PDF 的时候可能会导致右边边界中文字符越界

可能的原因是在于，xelatex 默认是英文断行，会导致换行有些问题，需要在 head.tex 中显示的应用中文断行规则。在xelatex的配置导言区中添加如下指令。

\XeTeXlinebreaklocale "zh"
\XeTeXlinebreakskip = 0pt plus 1pt minus 0.1pt
\usepackage[top=2cm, bottom=1.5cm, left=2cm, right=2cm]{geometry}
...

参考

1. installing - How do I install an individual package on a Linux system? - TeX - LaTeX Stack Exchange