Reader 选项

--shift-heading-level-by=NUMBER

通过正整数或负整数来移动标题级别。例如，使用 —shift-heading-level-by=-1，二级标题变为一级标题，三级标题变为二级标题。标题的级别不能小于1，因此如果标题被移动到一级以下，它将变为普通段落。例外情况：使用 -N 的负移动，文档开头的级别为 N 的标题将替换元数据标题。对于将 HTML 或 Markdown 文档从使用一级标题作为文档标题和二级以上标题作为节标题的文档转换，—shift-heading-level-by=-1 是一个不错的选择。对于将使用一级标题作为节标题的 Markdown 文档转换为 HTML，因为 pandoc 使用一级标题来呈现文档标题，—shift-heading-level-by=1 可能是一个不错的选择。

--base-header-level=NUMBER

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

--indented-code-classes=CLASSES

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

--default-image-extension=EXTENSION

当图像路径/URL没有扩展名时，指定要使用的默认扩展名。这允许您在需要不同类型图像的格式之间使用相同的源。当前此选项仅影响 Markdown 和 LaTeX 读取器。

--file-scope[=true|false]

在组合多文件文档之前分别解析每个文件。这将使具有相同标识符的不同文件中的脚注按预期工作。如果设置了此选项，脚注和链接将不会跨文件工作。读取二进制文件（docx、odt、epub）会暗示 —file-scope。

如果使用 —file-scope 处理两个或更多文件，则将根据文件名添加前缀以消除歧义，并相应地调整内部链接。例如，在 subdir/file1.txt 中具有标识符 foo 的标题将其标识符更改为 subdirfile1.txtfoo。

此外，将根据文件名基于的标识符添加一个基于文件名的 Div，以便内部链接到文件名将指向此 Div 的标识符。

-F PROGRAM，--filter=PROGRAM

指定要用作过滤器的可执行文件，用于在解析输入之后和写入输出之前转换 pandoc AST。可执行文件应从 stdin 读取 JSON，并将 JSON 写入 stdout。 JSON 必须格式化为 pandoc 自己的 JSON 输入和输出那样。输出格式的名称将作为第一个参数传递给过滤器。因此，

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

等同于

  1. 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 将查找以下过滤器：

  • 指定的完整路径或相对路径（可执行文件或非可执行文件），
  • $DATADIR/filters（可执行文件或非可执行文件），其中 $DATADIR 是用户数据目录（请参见 —data-dir，上文提到的），
  • $PATH（仅可执行文件）。

过滤器、Lua 过滤器和 citeproc 处理将按照命令行上指定的顺序应用。

-L SCRIPT，—lua-filter=SCRIPT 以与 JSON 过滤器相似的方式转换文档，但使用 pandoc 内置的 Lua 过滤系统。给定的 Lua 脚本应返回一个 Lua 过滤器列表，这些过滤器将按顺序应用。每个 Lua 过滤器必须包含按应用过滤器函数的 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 会设置底层文档的元数据（可从过滤器访问，并且可能在某些输出格式中打印），并且在插入模板时会转义元数据值。

--metadata-file=FILE

从提供的 YAML（或 JSON）文件读取元数据。此选项可用于每种输入格式，但元数据文件中的字符串标量将始终解析为 Markdown。 （如果输入格式是 Markdown 或 Markdown 变体，则将使用相同的变体来解析元数据文件；如果是非 Markdown 格式，则将使用 pandoc 的默认 Markdown 扩展。）此选项可重复使用，以包含多个元数据文件；在命令行上后面指定的文件的值将优先于较早指定的文件中指定的值。首先在工作目录中搜索该文件，然后在用户数据目录的 metadata 子目录中搜索该文件（请参阅 —data-dir）。

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

保留制表符，而不是将它们转换为空格。 （默认情况下，pandoc 在解析其输入之前将制表符转换为空格。）请注意，这仅影响文字代码段和代码块中的制表符。正文中的制表符始终被视为空格。

--tab-stop=NUMBER

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

--track-changes=accept|reject|all

指定处理由 MS Word “跟踪更改” 功能产生的插入、删除和注释的方式。accept（默认）处理所有插入和删除。拒绝忽略它们。接受和拒绝都忽略注释。all 包括所有插入、删除和注释，在相应的 span 中包装插入、删除、注释开始和注释结束类，作者和更改时间包括在内。all 对于脚本编写很有用：仅在某个审阅者之前或在某个日期之前接受更改，例如。如果插入或删除段落，则 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 上的进展。此选项旨在供开发人员在诊断性能问题时使用。