用 Pandoc 处理 Markdown 文件的格式转化

Markdown 写起来很舒服，纯文本管理起来也很顺手，但是涉及交流的时候，毕竟还是非主流，而且在有些场合也显得不太“正式”，这时候就需要转换成其它格式。

常用的无非是 HTML 格式、MS Word 格式（是的，大微软我们难以绕开）和 pdf 格式。这时就可以祭出神器 Pandoc 了。

1. 我说它“神”是因为有两点：一、这是一个哲学教授写的工具，二、这是用 Haskell 写的……
2. 我用的是 macOS，下面的命令都是 macOS 上的，其实除了安装不一样之外，都大同小异。

需要安装的软件主要有两个：

brew install pandoc
brew cask wkhtmltopdf

一、markdown -> docx

这一步非常简单：

pandoc -o test.docx test.md

如果需要修改默认的格式，可以先用pandoc --print-default-data-file reference.docx > custom-reference.docx命令输出默认的格式，再把 custom-reference.docx 文件修改成你想要的格式，最后引用它就可以了：

pandoc --reference-doc=custom-reference.docx -o test.docx test.md

二、markdown -> html

也一样非常直接：

pandoc -s -o test.html test.md

三、markdown -> pdf

这一步曾经很纠结，一开始走的是"markdown->latex/xelatex->pdf"这条路，是成功了。不过上学时被 Tex 的中文支持折磨怕了，年纪大了不愿意无故折腾，不想多深入研究，所以修改多种字体、调整格式等就比较麻烦了。

Tex 这东西，确实是在学术领域更适合，以几年的血泪史奉劝一句：不建议凡人折腾。

然后就走了一条"markdown->html->pdf"的路，生活就幸福多了，在 Pandoc 1.16 之前，是先通过上面的方法转成 html 文档，再使用wkhtmltopdf命令转成 pdf，分了两步，但也非常干脆，没什么拖泥带水的。

从 1.16 开始 Pandoc 就直接支持使用 wkhtmltopdf 作为生成 pdf 的引擎了，于是完美的解决方案出现：

pandoc --pdf-engine=wkhtmltopdf -o test.pdf test.md

也可以只使用-t html选项，默认就是--pdf-engine=wkhtmltopdf。

使用这种方式时，margin-left, margin-right, margin-top, margin-bottom, footer-html, header-html 和 papersize 这几个可以直接在参数中设定，其它的格式可以（也只能）通过 --css 选项指定 CSS 文件来设置。

这对我来说够了，不过wkhtmltopdf的参数非常之多，所以如果想更精细的调整，还是可以使用两步的方法分别调用pandoc和wkhtmltopdf来实现。

四、几个有用的参数

除了上面最基本的-t、-f和-o等参数，还有几个我个人比较常用的参数：

• -c URL/--css=URL 指定 CSS 文件，这在生成 HTML 和 PDF 时都很有用
• --toc/--table-of-content 自动生成目录，可以使用--toc-depth=NUMBER来指定深度
• -s/--standalone 生成的文件会带头注和脚注，对 html 文件还能解决未指定编码的问题
• --self-contained 会将CSS、图片等嵌入到目标 html 文件中
• -N/--number-sections 自动生成章节编号，带 class unnumbered 的除外（即# Header {.unnumbered}或# Header {-}）

五、其它问题

1. pandoc 输入输出都是 utf-8，处理其它编码时可以使用iconv来转一下编码
2. 有时候输出的 pdf 文件还需要一个漂亮的封面，这时候就不要吊死在 markdown 上了，可以使用其它工具做一个 pdf 格式的，最后拼到生成的 pdf 文件之前就可以了，我使用的工具是 ghostscript，在 macOS 上可以通过 Homebrew 安装。
3. 对于自己常用的参数，可以写一些脚本封装一下来简化每次的输入，更进一步可以使用 makefile 来管理构建输出，个人使用的是 cmake，也是神器，有时间另行介绍
4. 用 git 或 github 管理 markdown 文件是一个非常不错的选择

写在最后

工具是死的，人是活的，不要纠结，先用熟练一种，有新方法时也不要排斥，不断更新自己的，这行过程中一直保持一种可以“信手拈来”的状态（所用的方法和工具不一定是最新最好的，熟练更重要）。