Pandoc 用户使用指南 - 扩展

某些读取器和写入器的行为可以通过启用或禁用各种扩展来进行调整。

可以通过在格式名称后添加 +EXTENSION 来启用扩展，通过添加 -EXTENSION 来禁用扩展。例如，--from markdown_strict+footnotes 是启用了脚注的严格 Markdown，而 --from markdown-footnotes-pipe_tables 是没有脚注或管道表的 Pandoc 的 Markdown。

Markdown 读取器和写入器大量使用了扩展。因此，仅由它们使用的扩展在下面的 Pandoc 的 Markdown 部分中进行介绍（参见 Markdown 变体 中的 commonmark 和 gfm）。接下来将介绍适用于其他格式的扩展。

需要注意的是，在 ipynb 格式中添加的 Markdown 扩展会影响 Jupyter 笔记本中的 Markdown 单元格（就像命令行选项如 --markdown-headings 一样）。

排版

扩展：smart

将直引号解释为弯引号，将 --- 解释为破折号，将 -- 解释为连接号，并将 ... 解释为省略号。在某些缩写之后插入不可断开的空间，例如 "Mr."。

此扩展可以为以下格式启用/禁用：

• 输入格式

  markdown, commonmark, latex, mediawiki, org, rst, twiki, html

• 输出格式

  markdown, latex, context, rst

• 默认情况下在以下格式中启用

  markdown, latex, context（输入和输出）

注意

如果您正在编写 Markdown，则 smart 扩展具有相反的效果：本来应为弯引号的内容会以直引号形式出现。

在 LaTeX 中，smart 表示使用标准 TeX 连字用于引号(`` 和 '' 用于双引号，` 和 ' 用于单引号)以及连字符(-- 用于连接号和 --- 用于破折号)。如果禁用了 smart，那么在读取 LaTeX 时，Pandoc 将直接解析这些字符。在写入 LaTeX 时，启用 smart 会告诉 Pandoc 在可能的情况下使用连字；如果禁用了 smart，Pandoc 将使用 Unicode 引号和连字符。

标题和章节

扩展：auto_identifiers

没有显式指定标识符的标题将根据标题文本自动分配一个唯一的标识符。

此扩展可以为以下格式启用/禁用：

• 输入格式 markdown, latex, rst, mediawiki, textile

• 输出格式 markdown, muse

• 默认情况下在以下格式中启用 markdown, muse

从标题文本推导标识符所使用的默认算法如下：

• 移除所有格式、链接等。
• 移除所有脚注。
• 移除所有非字母数字字符，除了下划线、破折号和句点。
• 将所有空格和换行符替换为破折号。
• 将所有字母字符转换为小写。
• 移除第一个字母前的所有内容（标识符不能以数字或标点符号开头）。
• 如果在此之后未留下任何内容，则使用标识符 section。

例如：

这些规则应该在大多数情况下允许从标题文本中确定标识符。例外情况是几个标题具有相同的文本；在这种情况下，第一个将获得如上所述的标识符；第二个将在其后附加-1；第三个在其后附加-2；依此类推。

（但是，如果启用了 gfm_auto_identifiers，则会使用不同的算法；参见下文。）

这些标识符用于提供由 --toc|--table-of-contents 选项生成的目录中的链接目标。它们也使得在一个文档的不同部分之间提供链接变得简单。例如，指向这一节的链接可能如下所示：

参阅关于[标题标识符](#heading-identifiers-in-html-latex-and-context)的部分。

然而，请注意，这种方法只在 HTML、LaTeX 和 ConTeXt 格式中有效。

如果指定了 --section-divs 选项，则每个部分将被包裹在一个 section（或一个 div，如果指定了 html4）中，并且标识符将被附加到包含的 <section>（或 <div>）标签而不是标题本身。这允许使用 JavaScript 操纵整个部分或在 CSS 中以不同方式处理它们。

扩展功能：ascii_identifiers

导致由 auto_identifiers 生成的标识符为纯 ASCII。去掉带重音的拉丁字母的重音，并忽略非拉丁字母。

扩展功能：gfm_auto_identifiers

更改由 auto_identifiers 使用的算法以符合 GitHub 的方法。空格转换为破折号 (-)，大写字母转为小写字母，除了 - 和 _ 之外的标点符号被删除。表情符号被替换为其名称。

数学输入

扩展 tex_math_dollars，tex_math_gfm，tex_math_single_backslash，和 tex_math_double_backslash 在关于 Pandoc 的 Markdown 的部分中进行了描述。

然而，也可以与 HTML 输入一起使用。这对于读取使用 MathJax 格式化的网页非常方便。

原始 HTML/TeX

以下扩展在 Pandoc 的 Markdown 的相关部分中有更详细的描述：

• raw_html 允许无法用 pandoc 的 AST 表示的 HTML 元素被解析为原始 HTML。默认情况下，此功能对于 HTML 输入已禁用。

• raw_tex 允许原始 LaTeX、TeX 和 ConTeXt 包含在文档中。此扩展可以针对以下格式启用/禁用（除 markdown 外）：

  • 输入格式

    latex、textile、html（仅环境、\ref 和 \eqref）、ipynb

  • 输出格式

    textile、commonmark

  注意

  当应用于 ipynb 时，raw_html 和 raw_tex 不仅影响 Markdown 单元格中的原始 TeX，还影响输出单元格中的数据，其 MIME 类型为 text/html 。由于 ipynb 阅读器尝试在给出多个选项时尽可能地保留最丰富的输出，因此在转换为如 docx 这样不允许原始 html 或 tex 的格式时，禁用 raw_html 和 raw_tex 可以获得最佳效果。

• native_divs 导致 HTML div 元素被解析为原生 pandoc Div 块。如果你想将它们解析为原始 HTML，请使用 -f html-native_divs+raw_html。

• native_spans 导致 HTML span 元素被解析为原生 pandoc Span 内联。如果你想将它们解析为原始 HTML，请使用 -f html-native_spans+raw_html。如果你想在将 HTML 转换为 Markdown 时丢弃所有 div 和 span ，你可以使用 pandoc -f html-native_divs-native_spans -t markdown 。

Literate Haskell 支持

扩展: literate_haskell

将文档视为 literate Haskell 源代码。

此扩展可以为以下格式启用/禁用：

• 输入格式

  markdown, rst, latex

• 输出格式

  markdown, rst, latex, html

如果您在上述格式之一后附加了 +lhs（或 +literate_haskell ），pandoc 将把文档视为 literate Haskell 源代码。这意味着

• 在 Markdown 输入中，“足迹” 部分将被解析为 Haskell 代码，而不是块引用。位于 \begin{code} 和 \end{code} 之间的文本也将被视为 Haskell 代码。对于 ATX 风格的标题，字符 '=' 将被用作 '#' 的替代。

• 在 Markdown 输出中，带有类名 haskell 和 literate 的代码块将以足迹渲染，并且 块引用将缩进一个空格，因此不会被视为 Haskell 代码。此外，标题将以 setext 风格（带下划线）而非 ATX 风格（使用 '#' 字符）渲染。（这是因为 ghc 将第一列中的 '#' 字符视为引入行号。）

• 在 restructured text 输入中，“足迹” 部分将被解析为 Haskell 代码。

• 在 restructured text 输出中，具有类名 haskell 的代码块将以足迹渲染。

• 在 LaTeX 输入中，在 code 环境中的文本将被解析为 Haskell 代码。

• 在 LaTeX 输出中，具有类名 haskell 的代码块将在 code 环境中渲染。

• 在 HTML 输出中，具有类名 haskell 的代码块将以类名 literatehaskell 和足迹渲染。

示例：

pandoc -f markdown+lhs -t html

读取使用 Markdown 规则格式化的 literate Haskell 源代码并写入普通的 HTML（没有足迹）。

pandoc -f markdown+lhs -t html+lhs

以包含足迹的 Haskell 代码写入 HTML，以便可以复制和粘贴为 literate Haskell 源代码。

请注意，GHC 期望足迹出现在第一列，因此缩进的 literate 代码块（例如，在项目环境内部）将不会被 Haskell 编译器识别。

其他扩展

扩展: empty_paragraphs

允许空段落。默认情况下会省略空段落。

此扩展可以为以下格式启用/禁用：

• 输入格式

  docx, html

• 输出格式

  docx, odt, opendocument, html, latex

扩展：native_numbering

启用原生的图形和表格编号。编号从 1 开始。

以下格式可以启用/禁用此扩展：

• 输出格式

  odt, opendocument, docx

扩展: xrefs_name

文档中对标题、图片和表格的链接会被替换为使用被引用项目名称或标题的交叉引用。生成的文档刷新后，原始链接文本会被替换。此扩展可以与 xrefs_number 结合使用，在这种情况下，编号会出现在名称之前。

交叉引用中的文本只有在文档刷新后才会与被引用项目保持一致。

以下格式可以启用/禁用此扩展：

• 输出格式

  odt, opendocument

扩展: xrefs_number

文档中对标题、图片和表格的链接会被替换为使用被引用项目编号的交叉引用。原始链接文本将被丢弃。此扩展可以与 xrefs_name 结合使用，在这种情况下，编号会出现在名称之后。

要使 xrefs_number 有用，生成的文档中必须启用标题编号，同时还需要通过例如使用 native_numbering 扩展来启用表格和图片的标题。

交叉引用中的编号只有在文档刷新后才能在最终文档中看到。

以下格式可以启用/禁用此扩展：

• 输出格式

  odt, opendocument

扩展: styles

从 docx 转换时，无论 pandoc 是否理解这些样式的意义，都将所有 docx 样式读取为段落样式的 div（对于段落样式）和字符样式的 span（对于字符样式）。可以与 docx 自定义样式 一起使用。默认禁用。

• 输入格式

  docx

扩展: amuse

在 muse 输入格式中，此功能启用 TextAmuse 对 Emacs Muse 标记的扩展。

扩展: raw_markdown

在 ipynb 输入格式中，这会导致 Markdown 单元格作为原始 Markdown 块包含（允许无损往返），而不是被解析。仅在您的目标是 ipynb 或基于 Markdown 的输出格式时使用。

扩展: citations (org)

当启用了 citations 扩展在 org 中，org-cite 和 org-ref 风格的引用将会被解析为 原生 pandoc 引用。

扩展: citations (docx)

当在 docx 中启用了 citations，Zotero 或 Mendeley 或 EndNote 插件插入的引用将会被解析为原生 pandoc 引用。（否则，由书目软件生成的格式化的引用将会被解析为普通文本。）

扩展: fancy_lists (org)

Pandoc 的 Markdown 高级列表的某些方面也被接受为在 org 输入中，模仿了 Emacs 中的选项 org-list-allow-alphabetical。与 Org 模式一样，启用此扩展允许除了阿拉伯数字之外还解析小写和大写的字母标记有序列表。请注意，对于 Org，这不包括罗马数字或由该扩展在 Pandoc 的 Markdown 中启用的 # 占位符。

扩展: element_citations

在 jats 输出格式中，这会导致参考项被替换为 <element-citation> 元素。这些 元素不受 CSL 样式的影响，但所有关于项目的资讯都包含在标签中。

扩展: ntb

在 context 输出格式中，这将启用使用 Natural Tables (TABLE) 而不是默认的 Extreme Tables (xtables)。自然表格允许更精细的全局自定义，但相比极端表格性能有所降低。

扩展: tagging

使用 context 输出启用此扩展将生成适合生产带有标签的 PDF 的标记。这包括 段落的附加标记和强调文本的替代标记。如果启用了扩展，则设置模板变量 emphasis-command。