Pandoc 的使用和遇到的问题

Pandoc 使用

前段时间换了电脑，直接拷过来的MarkDownPad出了点问题，再加上VSCode的MarkDown功能越来越好用了，索性就不再用额外的MarkDown编辑器，直接用VSCode算了，在装了markdownlint和vscode-pandoc两个插件之后就更好用了。为了使用vscode-pandoc，就开始了对Pandoc的探索，Pandoc是什么不需要多说，本文的重点在讨论Pandoc的折腾过程，Pandoc和VSCode的搭配使用挺简单的，也不需要多言。

安装

首先从github上获取最新版本，有5种版本可供选择，为了不用安装我下载了其pancoc-2.0.2-windows.zip版本，解压之后得到五个文件：.rtf与.txt文件应该都是版权声明文件，一个.html的用户指南，pandoc.exe、pandoc-citeproc.exe都是命令行工具。pandoc-citeproc.exe不清楚其作用，主要使用pandoc.exe来进行文件转换。

安装后的配置

• 安装之后，使用 pandoc --version 命令用于检查pandoc是否可用，这时候如果直接在任意处打开cmd来执行，windows可能不能识别此命令，需要将pandoc.exe的路径配置到环境变量中去

使用

md 转 docx

pandoc test.md -o test.docx

这个转换比较简单，不用多做配置

md 转 html

pandoc -s -f gfm -t html5 --css=css/markdownPad-github.css test.md -o test.html

• -s 表示使用标准模板输出
• -f gfm -t html5 表示用 gfm 引擎来解析，从 Github Flavored MarkDown 到 HTML5。从网上看的别人写的是-f markdown_github -t html，试着使用这个来编译会产生Warning，提示找不到markdown_github，用gfm替代，索性就直接在命令里使用gfm
• --css=css/markdownPad-github.css 把 markdownPad-github.css 这个css文件加到生成的HTML文件中，是其呈现出不同的样式
• test.md -o test.html 把test.md这个MarkDown文件输出成同的.html文件，这样使用有时候会有Warning，应该是需要把.html取一个与.md文件不同的名字
• 本想使用github-markdown.css来呈现 github 式的 MarkDown 文件，但生成的html文件并没有.markdown-body等 class 名字，应该是 html 模板的原因，后来改用markdownPad-github.css

md 转 pdf

pandoc --pdf-engine=xelatex --template=D:\tools\Pandoc\pm-template.latex test.md -o test.pdf

• pandoc 不能直接生成 pdf 文档，需要借助 LaTeX 引擎

LaTeX

LaTeX 是一种排版系统，之前看CSDN上一篇程序员之间鄙视链的文章，用LaTeX写文档的程序员处于该条鄙视链的顶端。然而我还是用MarkDown，但是要转pdf还是得借用LaTeX，下了3G多的TeX Live.iso文件，安装占用了5个G的硬盘空间，结果只是借用其系统生成个pdf，这...应该算是买椟还珠吧...

• Tex Live 是一个发布版 LaTeX 集成版本，包括了各种插件和宏，还有默认的编辑器TeXworks，用其语法可直接编辑生成pdf文档，然而不会那个语法
• Tex Live 下载后找到其中的 install-tl-windows.bat 文件，双击运行，除文件保存路径外的所有选项应为默认

生成pdf过程中的问题

• 执行命令：

pandoc --latex-engine=xelatex test.md -o test.pdf

• 编译出错：latex-engine has been removed. Use --pdf-engine instead.

替换为：pandoc --pdf-engine=xelatex test.md -o test.pdf

• 编译生成的pdf文件只有英文，中文不显示
  • 在网上找到江航同学的这篇文章，原因是没有指定中文字体
  • 在 cmd 中用 fc-list 查看所有安装的字体，fc-list :lang=zh 输出所有中文字体，我的cmd输出的中文乱码，执行chcp 65001打开 active code page 65001 可以看到正常的中文输出
  • 这里有个小坑，用 -V mainfont="Microsoft YaHei" 指定中文字体，必须是双引号，否则会报错

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

• 中文正常显示后，发现中文不换行。原因是 Pandoc 使用的 latex 模板文件需要修改
  • 看了几篇文章，他们都改用了Tzeng Yuxio的模板文件，下载该模板，修改命令为：

pandoc --pdf-engine=xelatex --template=pm-template.latex test.md -o test.pdf

• 报错：找不到 modules\template.latex 文件。各种找modules文件夹找不到，只好指定模板文件的绝对路径

pandoc --pdf-engine=xelatex --template=D:\tools\Pandoc\pm-template.latex test.md -o test.pdf

• 指定模板文件后，使用这个模板文件编译出错
  - 修改pm-template.latex 中设置的中文字体LiHei Pro为本机中已安装的中文字体
  - 重新编译再次报错，在input.log 日志文件中找到具体的报错信息

xeCJK warning: “CJKfamily-Unknown”
Unknown CJK family \CJKsfdefault' is being ignored.
Try to use\setCJKmonofont[…]{…}’ to define it.

• 解决办法就是在pm-template.latex 中加上 \setCJKmonofont{Courier New}，然后继续编译报错

! Undefined control sequence.
l.199 \tightlist

• 在这里找到了解决办法，在模板文件中加入下边代码

\newcommand{\tightlist}{%
  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}

• 改完之后再次执行命令进行编译，报错

Error producing PDF. ! File ended while scanning use of \end. 

• 在网上查找解决方法，说删除掉所有日志和其他几种文件再次编译，但是我多次尝试都还是报同样的错误。经过一个小时的折腾，终于发现是我在修改模板文件期间不小心删掉了一个大括号，心累...最后输入命令，成功生成了还算看得过去的pdf文档

pandoc --pdf-engine=xelatex --template=D:\tools\Pandoc\pm-template.latex test.md -o test.pdf

结语

初次接触Pandoc，对于它每个命令的含义、作用的理解还非常肤浅，难免有什么错漏，欢迎大家指出。

参考文章

• 用pandoc把markdown转换为html
• 用pandoc把markdown转化为pdf文档
• pandoc markdown 生成pdf文档