Pandoc 用户使用指南 - 介绍

简介

Pandoc 是一个 Haskell 库，用于从一种标记语言格式转换为另一种，同时它也是一个利用此库的命令行工具。

Pandoc 能够在众多标记语言和文字处理格式之间进行转换，包括但不限于多种 Markdown 变体、HTML、LaTeX 及 Word docx 文档。完整的输入和输出格式列表，请参见 --from 和 --to 选项。Pandoc 还能生成 PDF 输出，详情请见创建 PDF 部分。

Pandoc 增强版的 Markdown 语法包含了表格、定义列表、元数据块、脚注、引用、数学公式等更多功能。关于这部分的详细信息，请参考 Pandoc 的 Markdown 部分。

Pandoc 采用模块化设计：它由一组 “读取器” 和一组 “写入器” 构成。读取器负责解析特定格式的文本并生成文档的本地表示形式（即抽象语法树 AST），而写入器则将这个本地表示形式转换为目标格式。因此，增加一个输入或输出格式仅需添加相应的读取器或写入器即可。用户还可以运行自定义的 Pandoc 过滤器来修改中间的 AST。

由于 Pandoc 文档的中间表示形式相比许多它所转换的格式来说表达能力较弱，因此不能期望在每种格式与另一种格式之间的转换都是完美的。Pandoc 尽力保留文档的结构元素，但不保证格式细节如页边距大小的精确对应。而且，一些复杂的文档元素，如复杂的表格，可能无法适应 Pandoc 简单的文档模型。从 Pandoc 的 Markdown 转换到所有格式都力求完美，但从比 Pandoc Markdown 更富表现力的格式转换时，可能会有信息丢失的情况发生。

使用 pandoc

如果不指定任何 输入文件，则输入将从 标准输入（stdin）读取。输出默认到 标准输出（stdout）。要将输出写入文件，请使用 -o 选项：

pandoc -o output.html input.txt

默认情况下，pandoc 生成一个文档片段。若要生成一个独立的文档（例如，一个包含有效 <head> 和 <body> 的 HTML 文件），请使用 -s 或 --standalone 标志：

pandoc -s -o output.html input.txt

有关如何生成独立文档的更多信息，请参见模板部分。

如果提供了多个输入文件，pandoc 将先将它们全部连接起来（文件间以空白行分隔），然后再进行解析。（使用 --file-scope 选项可对文件单独进行解析。）

指定格式

输入和输出的格式可以通过命令行选项明确指定。输入格式可以使用 -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

支持的输入和输出格式在“选项”部分下文列出（参见 -f 了解输入格式，-t 了解输出格式）。你也可以使用 pandoc --list-input-formats 和 pandoc --list-output-formats 命令来打印支持的格式列表。

如果未明确指定输入或输出格式，Pandoc 将尝试根据文件名的扩展名猜测格式。例如，

pandoc -o hello.tex hello.txt

会将 hello.txt 从 Markdown 转换为 LaTeX。如果没有指定输出文件（使得输出发送到标准输出 stdout），或者输出文件的扩展名未知，输出格式将默认为 HTML。如果没有指定输入文件（意味着输入来自标准输入 stdin），或者输入文件的扩展名未知，输入格式将被假定为 Markdown。

字符编码

Pandoc 在输入和输出中均使用 UTF-8 字符编码。如果你当地的字符编码不是 UTF-8，你应该通过 iconv 命令将输入和输出转换为 UTF-8：

iconv -t utf-8 input.txt | pandoc | iconv -f utf-8

请注意，在某些输出格式（如 HTML、LaTeX、ConTeXt、RTF、OPML、DocBook 和 Texinfo）中，文档头部会包含有关字符编码的信息，但这些信息仅当你使用 -s/--standalone 选项时才会被包含进去。

创建 PDF 文档

要生成 PDF，需指定一个具有 .pdf 扩展名的输出文件：

pandoc test.txt -o test.pdf

默认情况下，Pandoc 使用 LaTeX 来创建 PDF，这要求已安装 LaTeX 引擎（参见下方的 --pdf-engine 选项）。或者，Pandoc 也可以使用 ConTeXt、roff ms 或 HTML 作为中间格式。为此，像之前一样指定一个 .pdf 扩展名的输出文件，但在命令行中添加 --pdf-engine 选项或使用 -t context、-t html、或 -t ms。用于从中间格式生成 PDF 的工具可通过 --pdf-engine 进行指定。

你可以通过变量控制 PDF 的样式，这取决于所使用的中间格式：请参阅针对 LaTeX 的变量、针对 ConTeXt 的变量、针对 wkhtmltopdf 的变量以及针对 ms 的变量。当使用 HTML 作为中间格式时，可以使用 --css 选项来设置样式。

为了调试 PDF 生成过程，查看中间表示形式会很有帮助：不使用 -o test.pdf，而是比如使用 -s -o test.tex 输出生成的 LaTeX 代码。然后，你可以用 pdflatex test.tex 来测试它。

使用 LaTeX 时，需要以下包（它们都包含在最近版本的 TeX Live 中）：amsfonts、amsmath、lm、unicode-math、iftex、listings（如果使用了 --listings 选项）、fancyvrb、longtable、booktabs、[multirow]（如果文档中有跨多行的单元格的表格）、graphicx（如果文档包含图像）、bookmark、xcolor、soul、geometry（配合设置的 geometry 变量）、setspace（配合 linestretch 设置）、以及 babel（配合设置的 lang）。如果设置了 CJKmainfont，则需要 xeCJK。如果代码高亮方案使用了带颜色背景，就需要 framed 包。使用 xelatex 或 lualatex 作为 PDF 引擎时，需要 fontspec。lualatex 使用 selnolig 和 lua-ul。xelatex 在设置了 dir 变量时使用 bidi。如果设置了 mathspec 变量，xelatex 将使用 mathspec 而非 unicode-math。如果可用，会使用 upquote 和 microtype 包；如果 csquotes 变量或元数据字段设置为真值，csquotes 将用于排版。natbib、biblatex、bibtex、和 biber 包可选地用于引用处理。以下包如果存在，将用来提高输出质量，但 Pandoc 不要求必须存在：upquote（在代码环境中使用直引号）、microtype（进行更好的间距调整）、parskip（提供更好的段落间距离）、xurl（在 URL 中实现更好的换行）、以及 footnotehyper 或 footnote（允许在表格中使用脚注）。

从网络读取

Pandoc 允许直接使用绝对网址作为输入，而非本地文件。在这种情况下，Pandoc 将通过 HTTP 协议获取内容：

pandoc -f html -t markdown https://www.fsf.org

在从 URL 请求文档时，可以提供自定义的 User-Agent 字符串或其他头部信息：

pandoc -f html -t markdown --request-header User-Agent:"Mozilla/5.0" https://www.fsf.org

这条命令表示，当 Pandoc 通过 URL 获取 HTML 文档并转换为 Markdown 格式时，会使用指定的 User-Agent 字符串Mozilla/5.0作为 HTTP 请求头中的 User-Agent 部分。这样可以模拟特定类型的浏览器或客户端进行网络请求。