Wenhui's Rotten Pen
文档格式转换工具Pandoc

文档格式转换工具Pandoc

本文

主要介绍一款文档格式转换工具Pandoc，它可以支持多种文档类型之间转换，包括Markdown、LaTeX、reStructuredText、HTML、Word docx 等。

版本 说明
0.1 初版发布

背景

  • 主机： Thinkpad S2
  • 系统： Deepin GNU/Linux 15.11
  • 内核： Debian 6.3.0-18+deb9u1

官网

什么是Pandoc

Pandoc，它可以将文档在 Markdown、LaTeX、reStructuredText、HTML、Word docx 等多种标记格式之间相互转换，并支持输出 PDF、EPUB、HTML 幻灯片等多种格式。该程序被称为格式转换界的 “瑞士军刀”。

Pandoc 的作者是 John MacFarlane，他是加州大学伯克利分校的哲学系教授。Pandoc 使用 Haskell 语言编写，被作者用来生成讲义、课件和网站等。该程序开源免费，目前以 GPL 协议托管在 Github 网站上。

安装

Pandoc 的作者已经为 Windows、macOS、Linux 等操作系统分别制作了对应的程序安装包。要使用该程序，只需下载对应的程序安装包进行安装即可。

对于 Ubuntu 等 Linux 发行版，Pandoc 已经被集成到系统的软件源内，因此还可以直接从软件源安装：

1

sudo apt-get install pandoc

使用方法

Pandoc 程序的命令使用方式为：

1

pandoc <files> <options>
  • 为输入的内容，其输入即可以来自文件，也可以来自标准输入甚至网页链接
  • 为参数选项。主要的参数选项有：
    • “-f 、-r ”：指定输入文件格式，默认为 Markdown；
    • “-t 、-w ”：指定输出文件格式，默认为 HTML；
    • “-o ”：指定输出文件，该项缺省时，将输出到标准输出；
    • “–highlight-style [style]”：设置代码高亮主题，默认为 pygments；
    • “-s”：生成有头尾的独立文件（HTML，LaTeX，TEI 或 RTF）；
    • “-S”：聪明模式，根据文件判断其格式；
    • “–self-contained”：生成自包含的文件，仅在输出 HTML 文档时有效；
    • “–verbose”：开启 Verbose 模式，用于 Debug；
    • “–list-input-formats”：列出支持的输入格式；
    • “–list-output-formats”：列出支持的输出格式；
    • “–list-extensions”：列出支持的 Markdown 扩展方案；
    • “–list-highlight-languages”：列出支持代码高亮的编程语言；
    • “–list-highlight-styles”：列出支持的代码高亮主题；
    • “-v、–version”：显示程序的版本号；
    • “-h、–help”：显示程序的帮助信息。

虽然 Pandoc 提供了用于指定输入输出格式的参数，但是很多时候该参数不必使用。Pandoc 已经足够聪明到可以根据文件名判断输入输出格式，所以除非文件名可能造成歧义，否则这两个参数都可以省略。

典型场景

markdown转html

  • 常规使用，输出的文档不包含任何样式，它的显示效果依赖于你使用的浏览器。
1

pandoc demo.md -o demo.html
  • 引入样式表CSS文件，使输出文档排版更精美。
1

pandoc demo.md -c style.css -o demo.html
  • 将本地图片等文件嵌入到输出文档。
1

pandoc demo.md --self-contained -c style.css -o demo.html
  • 添加目录。
1

pandoc demo.md --self-contained -c style.css --toc -o demo.html

org转html

与markdown转html使用相同，其实emacs自带org转html的插件，不过不能将外部文件嵌入到html，所以pandoc更实用。

另外多说一些，emacs中设置org文件中图片的显示大小和居中等设置，我还没有找到有效的方法，不过嵌入html代码是可以做到的图片的设置，但是pandoc转换时没有将其嵌入到html内部，所以我还是将org通过ox-hugo转为markdown，再进行markdown转html。看起来好像很麻烦，其实我平时都是使用hugo写博客，emacs、ox-hugo、hugo是日常必备，但是你不能要求所有人都使用emacs，往往需要与外界分享时才会转为html或者doc。

转为docx

1
2

pandoc demo.md -o demo.docx
pandoc demo.org -o demo.docx

将org和markdown文件转为docx的操作是一样的，不过直接转出的效果可能不会太乐观，可能需要二次编辑输出的文件，将标题、正文等调整为满意的样式。好在还可以为文档的格式提供一个简单参考模板（标题样式和正文样式等）。

1

pandoc test.org -o test.docx --reference-doc=template.docx

文档模板copy自ManateeLazyCat，这里给个链接地址。另外最简单创建模板的方法是:

  1. 先用命令 pandoc test.org -o template.docx 生成一个带Pandoc默认样式的Word文档。
  2. 用Office软件打开 template.docx 文件，修改样式成你喜欢的模样。
  3. 保存 template.docx 文件即可。

转为pdf文档

使用 Pandoc 直接生成 PDF 文件时，需要安装 LaTeX。并且，Pandoc 自带的 PDF 引擎不支持中文，必须为中文配置额外的引擎和模板。命令如下：

1

pandoc demo.md -o demo.pdf

我没有用过Pandoc生成pdf，只是将其功能列在这里，没使用过就不在多做描述。说实话，使用最多的功能就是将markdown转html并将外部文件内嵌其中，如果真需要pdf文件，可以使用浏览器的打印到pdf。

转为markdown

  • 我们可以将docx转换为 Markdown。
1

pandoc demo.docx -o demo.md
  • 甚至HTML网页转换为 Markdown（不只是本地html，网址也可以）。
1

pandoc  https://www.wenhui.space/about/ -o demo.md

也许转出的文档内容不一定让你满意，但是可能对于某些还是有这个需求吧，我使用的并不多。

其他场景

自行探索吧，如果有好用的欢迎分享。

css文件和word模板文件

上文提到了辅助转换的文件css和word模板，可以美化输出结果。

这里提供一个css文件，参考自使用Pandoc命令将Markdown格式文件转换为HTML格式文件。另外我又添加了标题的自动编号，不过要提醒的是，我一般不使用一级标题（hugo与org文件组织的原因），而是从二级标题开始，所以如果你使用一级标题，请进行修改。代码我就不展示了，提供一个网盘分享链接（包含word模板和linux64版Pandoc 1.17.2可执行文件）： 链接：https://pan.baidu.com/s/1BCmJuAufTa4HeA1c4UZ8CQ 密码：61vm

绑定emacs快捷键

请参考 高效创作 Mindmap -> Org-Mode -> Word。

其他进阶学习

pandoc是可以使用模板的，并且网上提供了很多资源，感兴趣的可以去探索，这里提供一些网址。有时候极致的追求是个无底洞，我不是偏执狂，所以就先到这里吧。如果您有好的使用方法，欢迎分享。

文章原创，可能存在部分错误，欢迎指正，联系邮箱 cao_arvin@163.com。

文章目录