安装好 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
  1. 更改 PDF 的 margin
pandoc --pdf-engine=xelatex -V geometry:"top=2cm, bottom=1.5cm, left=2cm,
right=2cm" -o test.pdf test.md
  1. 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
Logo

权威|前沿|技术|干货|国内首个API全生命周期开发者社区

更多推荐