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 部分。这样可以模拟特定类型的浏览器或客户端进行网络请求。