Pandoc 实用教程

Pandoc 是一种将各类文件互相转换的工具，例如 docx、html、markdown、epub、pdf 等，在一些 markdown 写作工具中，它常被用作导出工具的一种。

Pandoc 的安装

安装方法有很多种。

方案一：直接通过 Pandoc 提供的安装包

下载链接在 github 上

方案二：包管理应用

1. Mac 用户可以通过 Homebrew 来安装，brew install pandoc
2. Ubuntu / Debian 用户可以通过 sudo apt install pandoc 来安装
3. CentOS 可以通过 yum install pandoc 来安装
4. 也可以安装科学包管理工具 Anaconda ，过程中会自动安装 Pandoc

基础使用

请打开命令行工具。

# 读取文件
pandoc -f 输入格式 -t 输出格式 -o 输出文件名 输入文件
# 读取网页
pandoc -f html -t 输出格式 -o 输出文件名 --request-header User-Agent:"Mozilla/5.0" \
  https://www.fsf.org

可以通过以下命令查看更多选项帮助

pandoc --help
# 或
man pandoc

常见的输入 / 输出格式

格式	参数
CSV 表格	csv
Word 文档	docx
EPUB 电子书	epub
HTML 网页	html
Markdown 文档	markdown
PDF 文档（仅支持输出）	pdf
PPt 文档（仅支持输出）	pptx
JSON 数据	json

可以通过指令查看支持的格式

pandoc --list-input-formats
pandoc --list-output-formats

导出 Word 文档设置

--toc # 生成目录
--toc-depth=NUMBER # 生成的目录深度
--wrap=auto|none|preserve # 文字换行方式
--reference-doc=FILE # 指定模板

默认的 word 模板可以通过命令来查看

pandoc --print-default-data-file reference.docx > custom-reference.docx

默认的模板出现将在当前目录下的 custom-reference.docx 下，你可以对各个文字样式、默认表格样式进行修改。
Mac 的用户需要注意，使用 Pages 对模板文件进行修改会导致模板失效，需要使用 Office 进行编辑，并使用兼容模式进行保存。

文字样式可以在开始菜单中，找到对应的样式，进行修改

表格样式需要选中文档中的表格部分，选择 表格工具 > 设计 > 修改表格样式 来修改

修改完成后，可以通过 --reference-doc=custom-reference.docx 来指定模板。
也可以将模板文件放置到 Pandoc 的数据文件夹下，并命名为 reference.docx，后续 Pandoc 将把这个文件作为默认模板进行使用。
这里的数据文件夹，可以在 pandoc -v 指令的打印信息中，通过 data-dir 字段来获取。

导出 HTML 网页设置

-s 或 --standalone # 在生成的 html 文件中包含 head、body 等 html 文件的必要组成部分
--self-contained # 内嵌资源，不产生任何外部依赖
--data-dir=DIRECTORY # 读取资源的目录
# 模板设置
--template=FILE|URL # 使用模板进行渲染
-V KEY[=VAL], --variable=KEY[:VAL] # 将模板中的变量设置为对应的值

我们可以定制模板

pandoc --print-default-template=html > template.html # 查看默认的模板，并输出到 template.html

导出 EPUB 文档设置

--epub-cover-image=FILE # 设置封面
--epub-metadata=FILE # 设置媒体信息
--epub-embed-font=FILE # 设置字体

设置 metadata

metadata 是导出格式中的一些信息，例如作者、日期、简介等等，在 EPUB、PDF、Word 等格式中有一定作用。
可以在命令行中指定 metadata

-M KEY[=VAL], --metadata=KEY[:VAL] # 将 KEY 的内容设置为 VAL
--metadata-file=FILE # 读取 FILE 中的内容作为 metadata

也可以在文件中顶部对 metadata 进行声明，使用 YAML 语法

---
# 该部分必须在文档的顶部
# 顶部和底部的 三个横线必须保留
title: 标题
author:
- 作者 1
- 作者 2
date: 日期
keywords: [关键词 1, 关键词 2]
abstract: |
  第一段

  第二段
---