抠丁客 抠丁客
项目
编辑 (2024/8/4)

Pandoc 用户使用指南 - 选项

常规选项

-f FORMAT, -r FORMAT, --from=FORMAT, --read=FORMAT

指定输入格式。FORMAT 可以是：

  • BibTex （ BibTeX 参考书目 ）
  • biblatex （ BibLaTeX 参考书目 ）
  • bits （ BITS XML、 Jats 的别名 ）
  • commonmark （ CommonMark Markdown ）
  • commonmark_x （ CommonMark Markdown 与扩展 ）
  • creole（ 克里奥尔语 1.0 ）
  • csljson （ CSL JSON 参考书目 ）
  • csv（ CSV 表 ）
  • tSV （ TSV 表）
  • djot （ Djot 标记 ）
  • docbook （ DocBook ）
  • docx （ Word DOCX 文件 ）
  • DokuWiki （ 标记 ）
  • endnotexml（ EndNote XML 参考书目 ）
  • epub （ EPUB ）
  • fb2 （ FictionBook2 电子书 ）
  • gfm（ GitHub-Flavored Markdown ），或已弃用且准确性较低的 markdown_github; 仅在以下情况下使用 markdown_github 需要 GFM 不支持的扩展。
  • haddock（ 黑线鳕 标记 ）
  • html（ HTML ）
  • ipynb （ Jupyter 笔记本 ）
  • jats （ JATS XML ）
  • jira （ Jira/Confluence Wiki 标记 ）
  • json （ JSON 版本 原生 AST ）
  • latex（ LaTeX ）
  • markdown （ Pandoc 的 Markdown ）
  • markdown_mmd （ MultiMarkdown ）
  • markdown_phpextra （ PHP Markdown 额外 ）
  • markdown_strict（ 原始未扩展的 Markdown ）
  • mediawiki （ MediaWiki 标记 ）
  • man（ Roff Man ）
  • muse（ Muse ）
  • native（ 原生 Haskell ）
  • odt （ OpenOffice 文本 公文 ）
  • opml （ OPML ）
  • org（ Emacs Org 模式 ）
  • ris（ RIS 参考书目）
  • rtf（ 富文本格式 ）
  • rst （ reStructuredText ）
  • t2t （ txt2tags ）
  • textile（ Textile ）
  • tikiwiki（ 视频标记 ）
  • twiki （ TWiki 标记 ）
  • typst （ Typst ）
  • vimwiki （ Vimwiki ）
  • 自定义 Lua 读取器的路径，请参阅 自定义读取器和写入器

可以通过在格式名称后附加 +EXTENSION 或 -EXTENSION 来单独启用或禁用扩展。 请参阅 扩展，以获取 扩展及其名称。请参阅 --list-input-formats 和 --list-extensions。

-t FORMAT, -w FORMAT, --to=FORMAT, --write=FORMAT

指定输出格式。FORMAT 可以是：

  • asciidoc (modern AsciiDoc as interpreted by AsciiDoctor)
  • asciidoc_legacy (AsciiDoc as interpreted by asciidoc-py).
  • asciidoctor (deprecated synonym for asciidoc)
  • beamer (LaTeX beamer slide show)
  • bibtex (BibTeX bibliography)
  • biblatex (BibLaTeX bibliography)
  • chunkedhtml (zip archive of multiple linked HTML files)
  • commonmark (CommonMark Markdown)
  • commonmark_x (CommonMark Markdown with extensions)
  • context (ConTeXt)
  • csljson (CSL JSON bibliography)
  • djot (Djot markup)
  • docbook or docbook4 (DocBook 4)
  • docbook5 (DocBook 5)
  • docx (Word docx)
  • dokuwiki (DokuWiki markup)
  • epub or epub3 (EPUB v3 book)
  • epub2 (EPUB v2)
  • fb2 (FictionBook2 e-book)
  • gfm (GitHub-Flavored Markdown), or the deprecated and less accurate markdown_github; use markdown_github only if you need extensions not supported in gfm.
  • haddock (Haddock markup)
  • html or html5 (HTML, i.e. HTML5/XHTML polyglot markup)
  • html4 (XHTML 1.0 Transitional)
  • icml (InDesign ICML)
  • ipynb (Jupyter notebook)
  • jats_archiving (JATS XML, Archiving and Interchange Tag Set)
  • jats_articleauthoring (JATS XML, Article Authoring Tag Set)
  • jats_publishing (JATS XML, Journal Publishing Tag Set)
  • jats (alias for jats_archiving)
  • jira (Jira/Confluence wiki markup)
  • json (JSON version of native AST)
  • latex (LaTeX)
  • man (roff man)
  • markdown (Pandoc’s Markdown)
  • markdown_mmd (MultiMarkdown)
  • markdown_phpextra (PHP Markdown Extra)
  • markdown_strict (original unextended Markdown)
  • markua (Markua)
  • mediawiki (MediaWiki markup)
  • ms (roff ms)
  • muse (Muse)
  • native (native Haskell)
  • odt (OpenOffice text document)
  • opml (OPML)
  • opendocument (OpenDocument)
  • org (Emacs Org mode)
  • pdf ( PDF )
  • plain (plain text)
  • pptx ( PowerPoint slide show)
  • rst (reStructuredText)
  • rtf (Rich Text Format)
  • texinfo (GNU Texinfo)
  • textile (Textile)
  • slideous (Slideous HTML and JavaScript slide show)
  • slidy (Slidy HTML and JavaScript slide show)
  • dzslides (DZSlides HTML5 + JavaScript slide show)
  • revealjs (reveal.js HTML5 + JavaScript slide show)
  • s5 (S5 HTML and JavaScript slide show)
  • tei (TEI Simple)
  • typst (typst)
  • xwiki (XWiki markup)
  • zimwiki (ZimWiki markup)
  • 自定义 Lua 写入器的路径，请参阅下面的 自定义读取器和写入器

注意

odt、docx、epub 和 pdf 格式的输出不会被直接导向标准输出（stdout），除非使用 -o - 强制输出到标准输出。

可以通过在格式名称后附加 +EXTENSION 或 -EXTENSION 来单独启用或禁用扩展功能。关于扩展功能及其名称的列表，请参见 扩展 部分。更多详情，请参考 --list-output-formats 和 --list-extensions 选项。

-o FILE, --output=FILE

将输出写入 FILE 而非标准输出（stdout）。如果 FILE 为-，即使指定了非文本格式（如 docx、odt、epub2、epub3），输出也会被导向标准输出。如果输出格式为 chunkedhtml 且 FILE 没有扩展名，Pandoc 将不会生成 .zip 文件，而是在名为 FILE 的目录下解压该 zip 存档（除非 FILE 已存在，这种情况下会引发错误）。

--data-dir=DIRECTORY

指定用户数据目录以搜索 Pandoc 数据文件。如果不指定此选项，将使用默认的用户数据目录。在 *nix 和 macOS 系统上，这通常是 XDG 数据目录（默认为 $HOME/.local/share ，可通过设置 XDG_DATA_HOME 环境变量覆盖）下的 pandoc 子目录。如果该目录不存在但存在 $HOME/.pandoc ，将使用它（为了向后兼容）。在 Windows 系统上，默认的用户数据目录是 %APPDATA%\pandoc 。你可以通过运行 pandoc --version 查看系统上的默认用户数据目录。放置在这个目录中的数据文件（例如，reference.odt、reference.docx、epub.css、templates）将覆盖 Pandoc 的默认设置。（注意，用户数据目录不由 Pandoc 创建，需要你自己创建以使用它。）

-d FILE, --defaults=FILE

指定一组默认选项设置。FILE 是一个 YAML 文件，其字段对应于命令行选项设置。所有文档转换选项，包括输入和输出文件，都可以通过默认设置文件来设定。该文件首先在工作目录中查找，然后在用户数据目录的 defaults 子目录中查找（见 --data-dir）。可以省略 .yaml 扩展名。有关文件格式的更多信息，请参见 Defaults files 部分。默认设置文件中的设置可能会被命令行后续的选项覆盖或扩展。

--bash-completion

生成一个 bash 自动补全脚本。要启用 Pandoc 的 bash 自动补全，将以下内容添加到你的 .bashrc 中：

eval "$(pandoc --bash-completion)"

--verbose

提供详细的调试输出。

--quiet

抑制警告信息的显示。

--fail-if-warnings[=true|false]

如果有任何警告，以错误状态退出。

--log=FILE

以机器可读的 JSON 格式将日志消息写入 FILE。无论 --verbose 或 --quiet 的设置如何，所有 DEBUG 级别及以上的消息都将被记录。

--list-input-formats

列出行支持的输入格式，每行一个。

--list-output-formats

列出行支持的输出格式，每行一个。

--list-extensions[=FORMAT]

列出 FORMAT 支持的扩展，每个扩展前有一个+或-表示其是否在 FORMAT 中默认启用。如果不指定 FORMAT，默认给出 Pandoc Markdown 的设置。

--list-highlight-languages

列出支持的语法高亮语言，每行一个。

--list-highlight-styles

列出支持的语法高亮风格，每行一个。参见--highlight-style。

-v, --version

打印版本信息。

-h, --help

显示使用说明。

读取选项

--shift-heading-level-by=NUMBER

调整标题级别，通过正数或负数整数。例如，使用 --shift-heading-level-by=-1 时，二级标题变为一级标题，三级标题变为二级标题。标题级别不能低于 1，因此被移至级别 1 以下的标题将变成普通段落。例外情况是，当偏移为 -N 时，文档开头的 N 级标题会替换元数据标题。--shift-heading-level-by=-1 适用于将使用初始一级标题作为文档标题、二级及以上标题作为章节的 HTML 或 Markdown 文档转换。而 --shift-heading-level-by=1 可能适合将使用一级标题作为章节的 Markdown 文档转换为 HTML，因为 Pandoc 使用一级标题来呈现文档标题。

--base-header-level=NUMBER（已废弃）

使用 --shift-heading-level-by=X 代替，其中 X = NUMBER - 1。指定标题的基本级别（默认为 1）。

--indented-code-classes=CLASSES

为缩进式代码块指定使用的类，如 perl,numberLines 或 haskell 。多个类可以用空格或逗号分隔。

--default-image-extension=EXTENSION

当 paths/URLs 没有扩展名时，指定一个默认的扩展名。这允许你为需要不同类型图像的格式使用相同的源文件。目前该选项仅影响 Markdown 和 LaTeX 阅读器。

--file-scope[=true|false]

对于多文件文档，在合并之前逐个解析每个文件。这样将使得不同文件中具有相同标识符的脚注能够如预期般正常工作。如果设置了此选项，脚注和链接将无法跨文件生效。读取二进制文件（如 docx、odt、epub）时会默认启用 --file-scope 选项。

如果使用 --file-scope 选项处理两个或更多文件，将会根据文件名添加前缀至标识符中，以便明确区分它们，并相应地调整内部链接。例如，位于子目录 subdir 下的 file1.txt 文件中，标识符为 foo 的标题，其标识符将会被改为 subdirfile1.txtfoo。

-F PROGRAM, --filter=PROGRAM

指定一个可执行文件作为过滤器，用以在解析输入之后、输出之前转换 Pandoc 的抽象语法树（AST）。该可执行文件应从标准输入读取 JSON 数据，并将处理后的 JSON 数据输出到标准输出。JSON 数据的格式需遵循 Pandoc 自身的 JSON 输入输出格式。输出格式的名称将作为首个参数传递给过滤器。因此，

pandoc --filter ./caps.py -t latex

等效于

pandoc -t json | ./caps.py latex | pandoc -f json -t latex

后一种形式对于调试过滤器可能较为有用。

过滤器可以用任何编程语言编写。Text.Pandoc.JSON 模块导出了 toJSONFilter 函数，便于使用 Haskell 编写过滤器。偏好使用 Python 编写的用户可以利用从 PyPI 安装的 pandocfilters 模块。此外，也存在适用于 PHP、Perl 以及 JavaScript/node.js 的 Pandoc 过滤器库。

按照优先级顺序，Pandoc 会在以下位置查找过滤器：

  1. 指定的完整或相对路径（可执行或不可执行），
  2. 用户数据目录 $DATADIR 下的 filters 目录中（可执行或不可执行），其中 $DATADIR 是指通过 --data-dir 指定的目录，
  3. $PATH 环境变量中（仅限可执行文件）。

过滤器、Lua 过滤器以及 citeproc 引用处理将按照命令行中指定的顺序进行应用。

-L SCRIPT, --lua-filter=SCRIPT

以类似于 JSON 过滤器（参见 --filter ）的方式转换文档，但使用 Pandoc 内置的 Lua 过滤系统。所提供的 Lua 脚本应返回一个 Lua 过滤器列表，这些过滤器将按顺序应用。每个 Lua 过滤器必须包含由抽象语法树（AST）元素的名称索引的元素转换函数，即过滤函数应在哪个 AST 元素上应用。

Pandoc 提供的 Lua 模块包含了用于元素创建的辅助函数。它会自动加载到脚本的 Lua 环境中。

有关更多详细信息，请参阅 Lua 过滤器 文档。

按照优先级顺序，Pandoc 会在以下位置查找 Lua 过滤器：

  • 指定的完整或相对路径，
  • 用户数据目录 $DATADIR 下的 filters 目录，其中 $DATADIR 是通过 --data-dir 指定的。

过滤器、Lua 过滤器以及 citeproc 处理将按照命令行中指定的顺序执行。

-M KEY[=VAL], --metadata=KEY[:VAL]

将元数据字段 KEY 的值设置为 VAL。在命令行上指定的值将覆盖使用 YAML 元数据块 在文档中指定的值。值会被解析为 YAML 布尔型或字符串型。如果没有指定值，则该值将被视为布尔值 true。类似于 --variable ， --metadata 会让模板变量被设置。但与 --variable 不同的是，--metadata 会影响到底层文档的元数据（这部分元数据可被过滤器访问，并且在某些输出格式中可能被打印出来），而且当元数据值插入到模板中时，它们会被转义处理。

--metadata-file=FILE

从提供的 YAML（或 JSON）文件中读取元数据。此选项可与每种输入格式一起使用，但在元数据文件中的字符串标量将始终按 Markdown 格式解析。（如果输入格式是 Markdown 或其变体，则使用相同的变体来解析元数据文件；如果是非 Markdown 格式，Pandoc 将使用默认的 Markdown 扩展名。）此选项可以重复使用以包含多个元数据文件；命令行中后续指定的文件中的值将优先于之前文件中的值。在文档内部指定的元数据值，或使用 -M 选项指定的值，会覆盖通过此选项指定的值。文件将首先在工作目录中搜索，然后在用户数据目录的 metadata 子目录中搜索（ 参见 --data-dir ）。

-p, --preserve-tabs[=true|false]

保留制表符，而不是将其转换为空格。（默认情况下，Pandoc 在其解析输入之前会将制表符转换为空格。）请注意，这只会影响到代码片段和代码块中的制表符。常规文本中的制表符始终被视为空格。

--tab-stop=NUMBER

指定每个制表符占有的空格数（默认为 4）。

--track-changes[=accept|reject|all]

指定如何处理由 MS Word “跟踪修订” 功能产生的插入、删除和评论。接受（默认）处理所有插入和删除。拒绝则忽略它们。接受和拒绝都会忽略评论。全部会包含所有插入、删除和评论，这些内容分别包裹在带有插入、删除、注释开始和注释结束类的 span 元素中。变更的作者和时间也会包括在内。全部选项对于脚本编写很有用，比如只接受特定审阅者的修改，或者在某个日期之前的修改。如果插入或删除了段落，track-changes=all 会在受影响的段落换行前生成一个带有 paragraph-insertion/paragraph-deletion 类的 span。此选项仅影响 docx 阅读器。

--extract-media=DIR

将源文档中包含或链接的图像和其他媒体文件提取到 DIR 路径下，如果必要的话会创建该目录，并调整文档中图像引用，使它们指向提取出的文件。根据需要，媒体文件会被下载、从文件系统读取或从二进制容器（如 docx）中提取。如果原始文件路径是不包含...的相对路径，则使用这些路径；否则，文件名将根据内容的 SHA1 哈希值构建。

--abbreviations=FILE

指定一个自定义缩写词文件，每行一个缩写词。如果不指定此选项，Pandoc 将从用户数据目录读取缩写词数据文件，或回退到系统默认值。要查看系统默认值，可以使用 pandoc --print-default-data-file=abbreviations 。Pandoc 唯一使用这个列表的地方是在 Markdown 阅读器中。在此列表中找到的字符串后面会跟一个不间断空格，并且在 LaTeX 等格式中，句点不会产生句子结束的空格。这些字符串中不得包含空格。

--trace[=true|false]

打印诊断输出，跟踪解析器进度到标准错误输出（ stderr ）。此选项旨在供开发人员在诊断性能问题时使用。

常规写入器选项

-s, --standalone

生成带有适当头部和尾部的输出（例如，独立的 HTML、LaTeX、TEI 或 RTF 文件，而非片段）。此选项对 pdf、epub、epub3、fb2、docx 和 odt 输出格式会自动设置。对于本地输出格式，此选项会导致元数据被包含；否则，元数据将被抑制。

--template=FILE|URL

使用指定的文件作为生成文档的自定义模板。隐含 --standalone。关于模板语法的描述，请参见的 模板 部分。如果未指定扩展名，将根据编写器自动添加相应的扩展名，因此对于 HTML 输出，--template=special 会查找 special.html。如果找不到模板，pandoc 将在用户数据目录的 templates 子目录中搜索（参见 --data-dir）。如果不使用此选项，将使用适合输出格式的默认模板（参见 -D/--print-default-template ）。

-V KEY[=VAL], --variable=KEY[:VAL]

在独立模式下渲染文档时，将模板变量 KEY 设置为值 VAL。如果未指定 VAL，则该键将被赋予 true 的值。

--sandbox[=true|false]

在沙盒环境中运行 pandoc，限制读取器和写入器的 IO 操作仅限于命令行上指定的文件。请注意，此选项不会限制过滤器通过 PDF 文档生成过程中的 IO 操作。但它确实提供了安全防护，例如防止通过包含指令泄露文件。任何使用 pandoc 处理不受信任的用户输入的人都应使用此选项。

注意

某些读取器和写入器（例如，docx）需要访问数据文件。如果这些文件存储在文件系统上，那么当以 --sandbox 模式运行 pandoc 时，pandoc 将无法找到它们并会引发错误。对于这些应用，我们建议使用通过 embed_data_files 选项编译的 pandoc 二进制文件，这会使数据文件嵌入到二进制文件中而不是存储在文件系统上。

-D FORMAT, --print-default-template=FORMAT

打印输出 FORMAT 的系统默认模板。（参见 -t 以获取可能的 FORMAT 列表。）用户数据目录中的模板将被忽略。此选项可与 -o/--output 一起使用以重定向输出到文件，但在命令行上 -o/--output 必须位于--print-default-template 之前。

注意

某些默认模板使用了局部模板，例如 styles.html。要打印这些局部模板，请使用 --print-default-data-file：例如，--print-default-data-file=templates/styles.html 。

--print-default-data-file=FILE

打印系统默认数据文件。用户数据目录中的文件将被忽略。此选项可以与 -o/--output 一起使用以将输出重定向到文件，但在命令行上 -o/--output 必须位于 --print-default-data-file 之前。

--eol=crlf|lf|native

手动指定行尾符号：crlf（用于 Windows），lf（用于 macOS/Linux/UNIX ），或 native（根据运行 pandoc 的操作系统的适当行尾符号）。默认值是 native。

--dpi=NUMBER

为像素与英寸/厘米之间的转换指定默认的每英寸点数( dpi )值。（技术上，正确的术语应该是 ppi：每英寸像素数。）默认值为 96dpi。当图像内部包含有关 dpi 的信息时，将使用编码的值而非此选项指定的默认值。

--wrap=auto|none|preserve

决定输出中文本（源代码，非渲染版本）如何换行。使用 auto（默认）时，pandoc 将尝试按照 --columns（默认为 72）指定的列宽来换行。使用 none 时，pandoc 将完全不进行换行。使用 preserve 时，pandoc 将尝试保留源文档中的换行（即，如果源中有非语义的新行，输出中也会有相应的非语义新行）。在 ipynb 输出中，此选项会影响 Markdown 单元格内容的换行。

--columns=NUMBER

指定行长度（以字符计）。这会影响生成源代码中的文本换行（见 --wrap）。它也影响纯文本表格中列宽的计算（见 表格 部分）。

--toc[=true|false], --table-of-contents[=true|false]

在输出文档中包含一个自动生成的目录（或者，在 latex、context、docx、odt、opendocument、rst 或 ms 的情况下，包含一个创建目录的指令）。除非同时使用 -s/--standalone 选项，否则此选项无效，并且对 man、docbook4、docbook5 或 jats 输出没有影响。

请注意，如果您通过 ms 生成 PDF，目录将出现在文档的开头，标题之前。如果您希望目录位于文档末尾，请使用选项 --pdf-engine-opt=--no-toc-relocation 。

--toc-depth=NUMBER

指定要在目录中包含的章节级别数量。默认值是 3（意味着级别 1、2 和 3 的标题将被列在目录中）。

--strip-comments[=true|false]

从 Markdown 或 Textile 源码中移除 HTML 注释，而不是将它们作为原始 HTML 传递给 Markdown、Textile 或 HTML 输出。当 markdown_in_html_blocks 扩展未设置时，这不适用于 raw HTML 块内的 HTML 注释。

--no-highlight

即使代码块和内联代码给出了语言属性，也禁用语法高亮。

--highlight-style=STYLE|FILE

指定用于突出显示源代码的着色风格。选项包括 pygments（默认）、kate、monochrome、breezeDark、espresso、zenburn、haddock 和 tango。有关 Pandoc 中语法高亮的更多信息，请参见 语法高亮 。另请参阅 --list-highlight-styles 。

除了 STYLE 名称外，还可以提供一个扩展名为 .theme 的 JSON 文件。这将被解析为 KDE 语法高亮主题（如果有效），并用作突出显示风格。

要生成现有风格的 JSON 版本，请使用 --print-highlight-style。

--print-highlight-style=STYLE|FILE

打印突出显示风格的 JSON 版本，该版本可以被修改、保存为带有 .theme 扩展名的文件，并与 --highlight-style 一起使用。此选项可与 -o/--output 一起使用以重定向输出到文件，但在命令行上 -o/--output 必须出现在 --print-highlight-style 之前 。

--syntax-definition=FILE

指示 Pandoc 加载一个 KDE XML 语法定义文件，该文件将用于适当标记的代码块的语法高亮。这可用于添加对新语言的支持或使用现有语言的修改后的语法定义。此选项可以重复使用以添加多个语法定义。

-H FILE, --include-in-header=FILE|URL

在文档头部的末尾直接包含 FILE 的内容。例如，这可用于在 HTML 文档中包含特殊的 CSS 或 JavaScript。此选项可以多次使用以在头部包含多个文件。它们将按照指定的顺序被包含。暗含 --standalone 选项。

-B FILE, --include-before-body=FILE|URL

在文档主体的开始处直接包含 FILE 的内容（例如，在 HTML 中位于 <body> 标签之后，或在 LaTeX 中位于 \begin{document} 命令之后）。这可用于在 HTML 文档中包含导航栏或横幅。此选项可以多次使用以包含多个文件。它们将按照指定的顺序被包含。同样暗含 --standalone 选项。请注意，如果输出格式为 odt，则此文件必须是适合插入文档主体的 OpenDocument XML 格式；如果输出为 docx，则此文件必须是适合的 OpenXML 格式。

-A FILE, --include-after-body=FILE|URL

在文档主体的末尾直接包含 FILE 的内容（在 HTML 中位于 </body> 标签之前，或在 LaTeX 中位于 \end{document} 命令之前）。此选项可以多次使用以包含多个文件。它们将按照指定的顺序被包含。同样暗含--standalone 选项。注意，如果输出格式为 odt，此文件必须是适合插入文档主体的 OpenDocument XML 格式；如果输出为 docx，则此文件必须是适当的 OpenXML 格式。

--resource-path=SEARCHPATH

指定搜索图片和其他资源的路径列表。在 Linux、UNIX 和 macOS 系统上，路径之间应由 : 分隔；在 Windows 系统上，应由 ; 分隔。如果不指定 --resource-path ，默认的资源路径为工作目录。请注意，如果指定了 --resource-path ，必须显式列出工作目录，否则将不会搜索它。例如：--resource-path=.:test 将按顺序搜索工作目录和 test 子目录。此选项可以多次使用。命令行中后面列出的搜索路径组件将优先于前面的组件被搜索，因此 --resource-path foo:bar --resource-path baz:bim 等同于 --resource-path baz:bim:foo:bar 。请注意，此选项仅在 pandoc 本身需要查找图像时（例如，生成 PDF 或 docx 文件时，或使用 --embed-resources 时）有效。在其他情况下（例如，pandoc 生成 LaTeX 或 HTML 时），它不会导致图像路径被重写。

--request-header=NAME:VAL

在发出 HTTP 请求时（例如，当命令行上给出 URL，或文档使用的资源需要下载时），将请求头 NAME 设置为值 VAL。如果您位于代理服务器后，还需要设置环境变量 http_proxy 为 http://....

--no-check-certificate[=true|false]

禁用证书验证以允许访问不安全的 HTTP 资源（例如，当证书不再有效或为自签名时）。

影响特定编写器的选项

--self-contained[=true|false]

这是 --embed-resources --standalone 的过时同义词。它用于创建一个包含所有必要资源的独立 HTML 文件。

--embed-resources[=true|false]

当设置为 true 时，此选项生成一个没有外部依赖的独立 HTML 文件，使用 data: URI 将链接的脚本、样式表、图像和视频的内容嵌入到 HTML 文件中。生成的文件应该是“自包含”的，即不需要任何外部文件或网络访问就能被浏览器正确显示。此选项仅适用于 HTML 输出格式，包括 html4、html5、html+lhs、html5+lhs、s5、slidy、slideous、dzslides 和 revealjs。绝对 URL 的脚本、图像和样式表将被下载；相对 URL 的则会相对于工作目录（如果第一个源文件是本地文件）或相对于基础 URL（如果第一个源文件是远程文件）来查找。具有属性 data-external="1" 的元素将被保留不变；它们链接的文档不会被合并进文档中。限制：通过 JavaScript 动态加载的资源无法被合并；因此，在使用 --mathjax 时可能会丢失字体，并且在离线的 “自包含” reveal.js 演示文稿中某些高级功能（例如缩放或演讲者注释）可能无法正常工作。

对于 SVG 图像，默认情况下使用带有 data: URI 的 img 标签，除非图像有 inline-svg 类，在这种情况下会插入内联 SVG 元素。当文档中有多个相同的 SVG 时推荐采用这种方法，因为 <use> 元素会被用来减少重复。

--html-q-tags[=true|false]

在 HTML 中使用 <q> 标签表示引号。（此选项只有在所使用的输入格式启用了 smart 扩展时才有效。）

--ascii[=true|false]

在输出中仅使用 ASCII 字符。目前此选项支持 XML 和 HTML 格式（当选择此选项时使用实体而不是 UTF-8），CommonMark、gfm 和 Markdown（使用实体），roff man 和 ms（使用十六进制转义序列），以及一定程度上的 LaTeX（尽可能使用标准命令表示带重音的字符）。

--reference-links[=true|false]

在生成 Markdown 或 reStructuredText 时使用参考式链接，而非内联链接。默认情况下使用内联链接。链接参考的位置受 --reference-location 选项的影响。

--reference-location=block|section|document

指定脚注（如果设置了 reference-links，则包括链接参考）放置于当前（顶级）区块的末尾、当前章节的末尾还是文档的末尾。默认值为 document。目前此选项只影响 markdown、muse、html、epub、slidy、s5、slideous、dzslides 和 revealjs 写入器。在幻灯片格式中，设置 --reference-location=section 会导致注释显示在幻灯片底部。

--markdown-headings=setext|atx

指定 Markdown 输出中的 1 级和 2 级标题使用 ATX 风格（以 # 前缀）或 Setext 风格（下划线标示）。默认值是 atx。对于 3 级及以上的标题始终使用 ATX 风格。此选项也会影响 ipynb 输出中的 Markdown 单元格。

--list-tables[=true|false]

在 RST 输出中将表格渲染为列表表格。

--top-level-division=default|section|chapter|part

在 LaTeX、ConTeXt、DocBook 和 TEI 输出中将顶级标题视为指定的章节类型。层级顺序为 part、chapter 然后是 section；所有标题都会调整，使得顶级标题变为指定的类型。默认行为是通过启发式方法确定最佳的章节类型：除非有其他条件适用，否则选择 section。当文档类变量设置为 report、book 或 memoir（除非指定了 article 选项），则默认 chapter 作为此选项的设置。如果输出格式为 beamer，指定 chapter 或 part 会使顶级标题变为 \part{..}，而二级标题保持其默认类型。

-N, --number-sections

在 LaTeX、ConTeXt、HTML、Docx、ms 或 EPUB 输出中对章节标题编号。默认情况下，章节不编号。具有 unnumbered 类别的章节永远不编号，即使指定了 --number-sections 也是如此。

--number-offset=NUMBER[,NUMBER,…]

HTML 输出中章节标题的偏移量（在其他输出格式中会被忽略）。第一个数字被加到顶级标题的章节号上，第二个数字被加到二级标题的章节号上，依此类推。例如，如果你想让你文档中的第一个顶级标题编号为 “6”，则指定 --number-offset=5。如果你的文档从一个二级标题开始，并且你想让这个标题编号为 “1.5”，则指定 --number-offset=1,4 。默认偏移量为 0。此选项隐含了 --number-sections。

--listings[=true|false]

在 LaTeX 代码块中使用 listings 包。该包不支持源代码的多字节编码。要处理 UTF-8，你需要使用自定义模板。这个问题在这里有完整说明：listings 包的编码问题 。

-i, --incremental[=true|false]

使幻灯片展示中的列表项逐个显示（一次一个）。默认情况下，列表会一次性全部显示。

--slide-level=NUMBER

指定使用特定级别的标题创建幻灯片（针对 beamer、revealjs、pptx、s5、slidy、slideous、dzslides）。此级别以上的标题用于划分幻灯片展示的各个部分；此级别以下的标题则在幻灯片内部创建子标题。有效值为 0 到 6。如果指定幻灯片级别为 0，则幻灯片不会自动根据标题分割，必须使用水平线来指示幻灯片边界。如果不明确指定幻灯片级别，将根据文档内容自动设置；参见 结构化幻灯片展示 。

--section-divs[=true|false]

用 <section> 标签（或 html4 中的 <div> ）包裹章节，并将标识符附加到外部的 <section>（或 <div> ）上，而不是标题本身（参见 标题标识符，下文）。此选项仅影响 HTML 输出（不影响 HTML 幻灯片格式）。

--email-obfuscation=none|javascript|references

指定混淆 HTML 文档中 mailto: 链接的方法。none 表示不处理 mailto: 链接。javascript 使用 JavaScript 进行混淆。references 通过打印字母的十进制或十六进制字符引用进行混淆。默认为 none。

--id-prefix=STRING

为所有 HTML 和 DocBook 输出中的标识符和内部链接以及 Markdown 和 Haddock 输出中的脚注编号指定前缀。这有助于在生成要包含在其他页面中的片段时防止标识符重复。

-T STRING, --title-prefix=STRING

指定 STRING 作为出现在 HTML 头部标题（但不在 HTML 正文开始处的标题）前的前缀。暗示 --standalone。

-c URL, --css=URL

链接到 CSS 样式表。此选项可以多次使用以包含多个文件。它们将按照指定的顺序被包含。此选项仅影响 HTML（包括 HTML 幻灯片）和 EPUB 输出。应与 -s/--standalone 一起使用，因为样式表的链接放在文档头部。

EPUB 生成需要样式表。如果没有使用此选项（或 css 或 stylesheet 元数据字段）提供，则 pandoc 将在用户数据目录（参见 --data-dir ）中查找 epub.css 文件。如果在那里找不到，将使用合理的默认值。

--reference-doc=FILE|URL

使用指定的文件作为生成 docx 或 ODT 文件的样式参考。

  • Docx
    为了获得最佳效果，参考 docx 应该是使用 pandoc 生成的 docx 文件的修改版。参考 docx 的内容将被忽略，但其样式表和文档属性（包括边距、页面大小、页眉、页脚）将用于新 docx。如果命令行上未指定参考 docx，pandoc 将查找用户数据目录（参见 --data-dir）中的 reference.docx 文件。如果这也找不到，将使用合理的默认值。

    要生成自定义的 reference.docx，首先获取默认的 reference.docx 的副本：pandoc -o custom-reference.docx --print-default-data-file reference.docx。然后在 Word 中打开 custom-reference.docx，根据需要修改样式，然后保存文件。为了获得最佳结果，请不要对这个文件做除了修改 pandoc 使用的样式之外的任何更改：

    段落样式：

    • 正常
    • 正文字体
    • 首段落
    • 紧凑
    • 标题
    • 副标题
    • 作者
    • 日期
    • 摘要
    • 抽象标题
    • 参考文献
    • 一级标题
    • 二级标题
    • 三级标题
    • 四级标题
    • 五级标题
    • 六级标题
    • 七级标题
    • 八级标题
    • 九级标题
    • 块引用文本
    • 脚注块引用文本
    • 源代码
    • 脚注文本
    • 定义项
    • 定义
    • 标题
    • 表格标题
    • 图像标题
    • 图形
    • 标题图形
    • 目录标题

    字符样式：

    • 默认段落字体
    • 正文字体字符
    • 纯文本字符
    • 脚注引用
    • 超链接
    • 节编号

    表格样式：

    • 表格

  • ODT
    为了获得最佳效果，参考 ODT 应该是使用 pandoc 生成的 ODT 的修改版。参考 ODT 的内容将被忽略，但其样式表将用于新 ODT。如果命令行上未指定参考 ODT，pandoc 将查找用户数据目录（参见 --data-dir ）中的 reference.odt 文件。如果这也找不到，将使用合理的默认值。

    要生成自定义的 reference.odt，首先获取默认的 reference.odt 的副本：pandoc -o custom-reference.odt --print-default-data-file reference.odt。然后在 LibreOffice 中打开 custom-reference.odt，根据需要修改样式，然后保存文件。

  • PowerPoint
    已知与 Microsoft PowerPoint 2013 附带的模板（具有 .pptx 或 .potx 扩展名）兼容，大多数基于这些模板的模板也兼容。

    具体要求是模板应包含以下名称的布局（在 PowerPoint 内看到）：

    • 标题幻灯片

    • 标题和内容

    • 部分标题

    • 两个内容

    • 对比

    • 带有说明的内容

    • 空白

      对于每个名称，pandoc 将使用找到的第一个具有该名称的布局。如果找不到带有上述任一名称的布局，pandoc 将输出警告并使用默认参考 doc 中的相应布局（ PowerPoint 布局选择 中描述了这些布局如何使用）。

      最近版本的 MS PowerPoint 附带的所有模板都符合这些标准。（你可以点击 “主页” 菜单下的 “布局” 来检查。）

      你也可以修改默认的 reference.pptx：首先运行 pandoc -o custom-reference.pptx --print-default-data-file reference.pptx ，然后在 MS PowerPoint 中修改 custom-reference.pptx（pandoc 将使用上面列出名称的布局）。

--split-level=NUMBER

指定在 EPUB 或分块 HTML 文档中根据标题级别将其拆分为单独文件的级别。默认是在一级标题处分割成章节。对于 EPUB 而言，此选项仅影响 EPUB 的内部组成，不影响用户查看章节和部分的方式。如果文档很大且一级标题很少，某些阅读器可能速度较慢，因此可能希望使用 2 级或 3 级作为章节级别。对于分块 HTML，此选项决定了每“块”中包含多少内容。

--chunk-template=PATHTEMPLATE

为分块 HTML 文档的文件名指定一个模板。在模板中，%n 将被替换为块号（前面填充 0 至三位数），%s 为块的节号，%h 为去除了格式的标题文本，%i 为节标识符。例如，%section-%s-%i.html 可能解析为 section-1.1-introduction.html。不允许在块模板中使用/和\字符，它们将被忽略。默认为 %s-%i.html。

--epub-chapter-level=NUMBER

废弃的同义词为 --split-level。

--epub-cover-image=FILE

使用指定的图像作为 EPUB 封面。建议图像的宽度和高度都小于 1000px。请注意，在 Markdown 源文档中，你也可以在 YAML 元数据块中指定 cover-image（参见 EPUB 元数据 ）。

--epub-title-page=true|false

决定是否在 EPUB 中包含标题页（默认为 true）。

--epub-metadata=FILE

在指定的 XML 文件中查找 EPUB 的元数据。文件应包含一系列 Dublin Core 元素。例如：

<dc:rights>Creative Commons</dc:rights>
<dc:language>es-AR</dc:language>

默认情况下，pandoc 将包含以下元数据元素：<dc:title>（来自文档标题）、<dc:creator>（来自文档作者）、<dc:date>（来自文档日期，应为 ISO 8601 格式）、<dc:language>（来自 lang 变量，如果没有设置，则来自区域设置），以及<dc:identifier id="BookId">（随机生成的 UUID）。元数据文件中的任何元素都可以覆盖这些默认值。

注意

如果源文档是 Markdown，可以在文档中使用 YAML 元数据块代替。见下文关于 EPUB 元数据。

--epub-embed-font=FILE

将指定的字体嵌入 EPUB 中。此选项可以重复以嵌入多个字体。也可以使用通配符：例如，DejaVuSans-*.ttf。然而，如果你在命令行中使用通配符，请确保对其进行转义或者将整个文件名用单引号括起来，以防止它们被 shell 解释。为了使用嵌入的字体，你需要在 CSS 中添加类似下面这样的声明（参见 --css）:

@font-face {
  font-family: DejaVuSans;
  font-style: normal;
  font-weight: normal;
  src: url("../fonts/DejaVuSans-Regular.ttf");
}
@font-face {
  font-family: DejaVuSans;
  font-style: normal;
  font-weight: bold;
  src: url("../fonts/DejaVuSans-Bold.ttf");
}
@font-face {
  font-family: DejaVuSans;
  font-style: italic;
  font-weight: normal;
  src: url("../fonts/DejaVuSans-Oblique.ttf");
}
@font-face {
  font-family: DejaVuSans;
  font-style: italic;
  font-weight: bold;
  src: url("../fonts/DejaVuSans-BoldOblique.ttf");
}
body {
  font-family: "DejaVuSans";
}

--epub-subdirectory=DIRNAME

指定 OCF 容器中用于存放 EPUB 特定内容的子目录。默认值是 EPUB 。若要将 EPUB 内容置于顶层，可使用空字符串。

--ipynb-output=all|none|best

决定如何处理 ipynb 输出单元。all 意味着原始文件中包含的所有数据格式都将被保留。none 表示省略数据单元的内容。best 使 pandoc 尝试从每个输出单元中选择与输出格式兼容的最丰富的数据块。默认值是best。

--pdf-engine=PROGRAM

生成 PDF 输出时使用指定的引擎。有效值有：pdflatex、lualatex、xelatex、latexmk、tectonic、wkhtmltopdf、weasyprint、pagedjs-cli、prince、context、pdfroff 和 typst。如果引擎不在你的 PATH 中，可以在此处指定引擎的完整路径。如果不指定此选项，pandoc 将根据使用 -t/--to 指定的输出格式使用以下默认值：

  • -t latex或无：pdflatex（其他选项：xelatex、lualatex、tectonic、latexmk）
  • -t context：context
  • -t html：wkhtmltopdf（其他选项：prince、weasyprint、pagedjs-cli；关于从 HTML/CSS 生成 PDF 的优秀介绍，见 print-css.rocks ）
  • -t ms：pdfroff
  • -t typst：typst

--pdf-engine-opt=STRING

将给定的字符串作为命令行参数传递给 pdf-engine。例如，要为 latexmk 的辅助文件使用持久目录 foo，可以使用 --pdf-engine-opt=-outdir=foo 。请注意，不会进行重复选项检查。

引用呈现

-C, --citeproc

处理文件中的引用，将它们替换为渲染后的引用，并添加参考文献。除非通过外部文件（使用 --bibliography 选项或元数据中的 bibliography 字段指定）提供参考文献数据，或者通过元数据中的参考文献部分包含以 CSL YAML 格式和 Markdown 格式编排的引用列表，否则不会进行引用处理。引用样式由使用 --csl 选项或元数据中 csl 字段指定的 CSL 样式表控制。（如果没有指定样式表，默认将使用 chicago-author-date 风格。）引用处理转换可以在过滤器或 Lua 过滤器（见 --filter, --lua-filter）之前或之后应用：这些转换将按照命令行上的出现顺序应用。更多信息，请参阅关于 引用 的部分。

--bibliography=FILE

将文档元数据中的 bibliography 字段设置为 FILE，覆盖元数据中设置的任何值。如果您多次提供此参数，每个 FILE 都将被添加到参考文献中。如果 FILE 是一个 URL，它将通过 HTTP 获取。如果相对于工作目录找不到 FILE，将在资源路径（见 --resource-path）中寻找，最后在 pandoc 用户数据目录的 csl 子目录中寻找。

--csl=FILE

将文档元数据中的 csl 字段设置为 FILE，覆盖元数据中设置的任何值。（这等同于 --metadata csl=FILE。）如果 FILE 是一个 URL，它将通过 HTTP 获取。如果相对于工作目录找不到 FILE，将在资源路径（见 --resource-path）中寻找，最后在 pandoc 用户数据目录的 csl 子目录中寻找。

--citation-abbreviations=FILE

将文档元数据中的 citation-abbreviations 字段设置为 FILE，覆盖元数据中设置的任何值。（这等同于 --metadata citation-abbreviations=FILE。）如果 FILE 是一个 URL，它将通过 HTTP 获取。如果相对于工作目录找不到 FILE，将在资源路径（见 --resource-path）中寻找，最后在 pandoc 用户数据目录的 csl 子目录中寻找。

--natbib

在 LaTeX 输出中使用 natbib 进行引用。此选项不与 --citeproc 选项或 PDF 输出一起使用。它的目的是用于生成可以使用 bibtex 处理的 LaTeX 文件。

--biblatex

在 LaTeX 输出中使用 biblatex 进行引用。此选项不与 --citeproc 选项或 PDF 输出一起使用。它的目的是用于生成可以使用 bibtex 或 biber 处理的 LaTeX 文件。

数学公式在 HTML 中的渲染

默认情况下，尽可能使用 Unicode 字符来渲染 TeX 数学公式。公式会被放在一个带有 class="math" 的 span 标签中，以便根据需要将其样式与周围文本区别开来。然而，这种方法只适用于基础数学，通常你可能希望使用 --mathjax 或其他以下选项。

--mathjax[=URL]

在 HTML 输出中使用 MathJax 显示嵌入的 TeX 数学公式。TeX 数学公式将被置于 \(...\)（用于内联数学）或 \[\ ...\]（用于展示数学）之间，并用带有 math 类的 <span> 标签包裹。然后，MathJax JavaScript 将对其进行渲染。URL 应该指向 MathJax.js 加载脚本。如果不提供 URL，将插入到 Cloudflare CDN 的链接。

--mathml

将 TeX 数学转换为 MathML（在 epub3、docbook4、docbook5、jats、html4 和 html5 中）。这是 odt 输出的默认设置。MathML 被主要的网络浏览器和部分电子书阅读器原生支持。

--webtex[=URL]

将 TeX 公式转换为链接到外部脚本的 <img> 标签，该脚本将公式转换为图像。公式将被 URL 编码并与提供的 URL 拼接。对于 SVG 图像，例如可以使用 --webtex https://latex.codecogs.com/svg.latex? 。如果没有指定 URL，将使用生成 PNG 的 CodeCogs URL（https://latex.codecogs.com/png.latex?）。注意：--webtex 选项会影响 Markdown 和 HTML 输出，这对于目标 Markdown 版本没有原生数学支持的情况非常有用。

--katex[=URL]

在 HTML 输出中使用 KaTeX 显示嵌入的 TeX 数学公式。URL 是 KaTeX 库的基础 URL。该目录应包含 katex.min.js 和 katex.min.css 文件。如果不提供 URL，将插入到 KaTeX CDN 的链接。

--gladtex

在 HTML 输出中将 TeX 数学公式包围在 <eq> 标签中。随后，可以使用 GladTeX 处理生成的 HTML 以产生公式的 SVG 图像和嵌入这些图像的 HTML 文件。

pandoc -s --gladtex input.md -o myfile.htex
gladtex -d image_dir myfile.htex
# 生成 myfile.html 及 image_dir 中的图像

Wrapper 脚本的选项

--dump-args[=true|false]

将命令行参数的信息打印到 stdout，然后退出。此选项主要用于 wrapper 脚本中。输出的第一行包含使用 -o 选项指定的输出文件名，如果没有指定输出文件，则为 -(表示 stdout)。剩余的每一行包含命令行参数，按其出现的顺序，每个参数一行。这些不包括普通的 pandoc 选项及其参数，但包括在行尾 -- 分隔符之后出现的任何选项。

--ignore-args[=true|false]

忽略命令行参数（用于 wrapper 脚本）。普通的 pandoc 选项不会被忽略。因此，例如，

pandoc --ignore-args -o foo.html -s foo.txt -- -e latin1

等同于

pandoc -o foo.html -s
在本文档中