文档格式转换工具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。