Pandoc API 上手指南

Pandoc 简介

Pandoc 是用来转换标记格式的 Haskell 库。也包含对应的命令行工具。

Pandoc 能够转换多种标记格式和字符处理格式。包括但不限于多种 Markdown 格式，HTML 格式，LaTex 和 docx 格式。可以通过查看下面的 --from 和 --to 选项来查看支持的所有输入以及输出格式。Pandoc 也可以生成 PDF 文件，具体参见创建 PDF 章节。

Pandoc 也支持 Markdown 的加强版格式，比如 tables 语法、自定义列表，metadata 块，脚注，引用，math 等待，具体参见 Pandoc Markdown 章节。

Pandoc 采用模块化的设计，它包含多种可以以指定格式读取文本并原生展示（抽象语法树）的 reader 以及一组 writer, writer 主要用来将原生展示输出为目标格式。所以，新增一种格式只需要定义对应的 reader 和 writer 即可，用户也可以通过自定义 pandoc filter(过滤器) 来修改产生的抽象树。

因为 Pandoc 针对文档生成的中间态相比目标格式和原格式而言会缺乏一些表现力，所以不能指望在格式之间完美转换。Pondoc 主要功能是保留文档中的结构化元素，而对于一些类似外间距（margin）的展示可能不准。对于其他文档 元素，比如复杂的 tables, 可能不太适用于 pandoc 的简单文档模型（simple document model）。最佳实践是从 Pandoc 的 markdown 格式转换到其他格式，从更富有表现力的格式转换到 markdown 会有有一部分损失。

开始使用 Pandoc

如果没有指定输入的源文件，默认从标准输入进行读取，默认输出是标准输出，如果要输出到文件的话，可以使用 -o 选项。

`pandoc -o output.html input.txt`

默认情况下 Pandoc 产生文件片段，如果要输出单独的文档（例如完整的包含 head 和 body 标签的 HTML 文档的话，需要使用 -s 或者 --standalone 标识符号）

`pandoc -s -o output.html input.txt`

想要了解更多关于如何生成单独的文件，可以参见 Template 部分。

如果有多个输入文件的话，Pandoc 会在解析这些文件之前，将它们通过空行连接起来。

输出指定格式

输入和输出格式可以通过命令行参数来显式指定，输入格式可以通过 -f 或者 --from 参数来指定。输出格式使用 -t 或者 --to 选项来指定，可以通过下面的命令将 hello.txt 将文件从 markdown 转换为 LaTeX 格式。

pandoc -f markdown -t latex hello.txt

下面的命令将 hello.html 从 HTML 转换到 Markdown:

pandoc -f html -t markdown hello.html

Pandoc 支持的格式可以在下面的 Options 章节看到（-f 查看支持的输入格式， -t 查看支持的输出格式），你也可以用使用 --list-input-formats 和 pandoc --list-output-formats 来查看支持的输入和输出格式。

如果不显示指定数输入或者输出格式，pandoc 会尝试根据文件后缀去猜，例如

pandoc -o hello.tex hello.txt

会将 hello.txt 从 Markdown 转化为 LaTeX 格式。如果没有指定输出到文件（会默认输出到标准输出），如果没有指定输出文件的后缀的话会默认为 HTML 格式。如果没有指定输入文件的话默认是标准输入，如果没有指定输入文件格式的话会默认为 Markdown。