Pandoc 用户使用指南 - Pandoc's Markdown

Pandoc 理解 John Gruber 的 Markdown 语法的一个扩展且略有修订的版本。本文档解释了该语法，并指出了与原始 Markdown 的差异。除非另有说明，这些差异可以通过使用 markdown_strict 格式而不是 markdown 来抑制。可以启用或禁用扩展以更精细地指定行为。以下将进行描述。另见上面的扩展，了解适用于其他格式的扩展。

哲学

Markdown 设计为易于编写，并且更重要的是，易于阅读：

Markdown 格式的文档应该可以直接发布为纯文本，而不应看起来像是被标签或格式化指令标记过。-- John Gruber

这一原则指导了 Pandoc 在寻找表格、脚注和其他扩展的语法时所做的决定。

然而，在一个方面，Pandoc 的目标与 Markdown 最初的目标不同。虽然 Markdown 最初是为生成 HTML 而设计的，但 Pandoc 是为多种输出格式而设计的。因此，虽然 Pandoc 允许嵌入原始 HTML，但它并不鼓励这样做，并提供了其他非 HTML 方式来表示定义列表、表格、数学和脚注等重要文档元素。

段落

段落是一个或多个文本行后跟一个或多个空白行。换行符被视为空格，因此您可以按需要重新换行。如果您需要硬换行，则在一行的末尾放置两个或多个空格。

扩展: escaped_line_breaks

反斜杠后跟一个换行符也是一个硬换行。注意：在多行和网格表格单元格中，这是创建硬换行的唯一方式，因为单元格末尾的空格会被忽略。

标题

有两种类型的标题：Setext 和 ATX。

Setext 风格标题

Setext 风格的标题是一行文本，下面有一行由 = 符号（对于一级标题）或 - 符号（对于二级标题）组成的 “下划线”：

# 一级标题

## 二级标题

标题文本可以包含内联格式化，例如强调（参见下面的 内联格式化）。

ATX 风格标题

ATX 样式的标题由一个到六个 # 符号和一行文本组成，可选地后面跟着任意数量的 # 符号。行首的 # 符号的数量即为标题级别：

## 二级标题

### 三级标题

与 setext 风格的标题一样，标题文本可以包含格式化的内容：

# 一级标题，包含链接 [链接](/url) 和 斜体 文本

扩展: blank_before_header

原始 Markdown 语法不要求标题前有一个空白行。Pandoc 要求这样（当然，在文档开头除外）。要求空白行的原因是 # 符号很容易意外出现在行首（例如通过自动换行）。考虑下面的例子：

我喜欢他们的几种冰淇淋口味：
#22，例如，还有 #5。

扩展: space_in_atx_header

许多 Markdown 实现不需要 ATX 标题的 # 符号和标题文本之间有空格，因此 #5 bolt 和 #hashtag 都被视为标题。使用此扩展，pandoc 要求必须有空格。

标题标识符

参见上面的 auto_identifiers 扩展。

扩展: header_attributes

可以在标题文本所在的行末尾使用以下语法为标题分配属性：

{#identifier .class .class key=value key=value}

因此，下面这些标题都将被分配标识符 foo：

# 我的标题 {#foo}

## 我的标题 ## {#foo}

## 我的另一个标题 {#foo}

(此语法与 PHP Markdown Extra 兼容。)

请注意，尽管此语法允许分配类和键值属性，但写入器通常不会使用所有这些信息。标识符、类和键值属性在 HTML 和基于 HTML 的格式（如 EPUB 和 slidy）中使用。标识符在 LaTeX、ConTeXt、Textile、Jira 标记和 AsciiDoc 写入器的标签和链接锚点中使用。

具有类 unnumbered 的标题将不会编号，即使指定了 --number-sections。属性上下文中的单个破折号 (-) 等同于 unnumbered，并且在非英语文档中更优选。因此，

# 我的标题 {#}

等同于

# 我的标题 {.unnumbered}

如果同时存在 unlisted 类和 unnumbered 类，则标题将不会包含在目录中。(目前此功能仅在某些格式中实现：基于 LaTeX 和 HTML 的格式、PowerPoint 和 RTF。)

扩展: implicit_header_references

Pandoc 的行为好像每个标题都定义了引用链接一样。

因此，要链接到某个标题

# HTML 中的标题标识符

你可以简单地写

[HTML 中的标题标识符]

或者

[HTML 中的标题标识符][]

或者

[该节关于标题标识符的部分][HTML 中的标题标识符]

而不是显式给出标识符：

[HTML 中的标题标识符](#heading-identifiers-in-html)

如果有多个标题文本相同，则对应的引用仅链接到第一个，你需要使用显式链接来链接到其他的，如上所述。

像常规引用链接一样，这些引用也不区分大小写。

显式链接引用定义总是优先于隐式标题引用。因此，在下面的例子中，链接指向的是 bar 而不是 #foo：

# Foo

[foo]: bar

见 [foo]

块引用

Markdown 使用电子邮件约定来引用文本块。块引用是一个或多个段落或其他块元素（如列表或标题），每一行前都有一个 > 字符和可选的空格。（> 不必从左边界开始，但不应缩进超过三个空格。）

> 这是一个块引用。这
> 段落有两行。
>
> 1. 这是块引用内的列表。
> 2. 第二项。

还允许一种 “懒惰” 的形式，即每个块只需要在第一行有一个 > 字符：

> 这是一个块引用。这
> 段落有两行。

> 1. 这是块引用内的列表。
> 2. 第二项。

可以在块引用中包含其他块引用。也就是说，块引用可以嵌套：

> 这是一个块引用。
>
> > 块引用内的块引用。

如果 > 后面跟着一个可选的空格，则该空格将被视为块引用标记的一部分，而不是内容的缩进。因此，要在块引用中放置一个缩进的代码块，需要在 > 后面加上五个空格：

>     代码

扩展功能：blank_before_blockquote

原始 Markdown 语法不需要块引用之前有一个空白行。Pandoc 需要这个（当然，在文档开头除外）。要求的原因是在一行的开头出现 > 太容易出错了（可能是由于换行造成的）。所以，除非使用 markdown_strict 格式，否则下面的内容不会在 Pandoc 中产生嵌套的块引用：

> 这是一个块引用。
>
> > 由于默认启用了 `blank_before_blockquote`，因此并未嵌套

逐字（代码）块

缩进代码块

一个缩进四个空格（或一个制表符）的文本块会被视为原始文本：即，特殊字符不会触发特殊格式化，并且所有空格和换行都会被保留。例如，

if (a > 3) {
    moveShip(5 * gravity, DOWN);
}

最初的缩进（四个空格或一个制表符）不被视为原始文本的一部分，并在输出中删除。

注意：原始文本中的空白行不必以四个空格开头。

围栏代码块

扩展：fenced_code_blocks

除了标准的缩进代码块外，pandoc 还支持围栏代码块。这些代码块以一行三个或更多波浪线（ ~ ）开始，并以一行至少与起始行一样长的波浪线结束。这两行之间的所有内容都被视为代码。不需要缩进：

~~~~~~~
if (a > 3) {
  moveShip(5 * gravity, DOWN);
}
~~~~~~~

就像常规代码块一样，围栏代码块必须通过空白行与周围的文本分开。

如果代码本身包含一行波浪线或反引号，则只需在开头和结尾使用更长的一行波浪线或反引号：

~~~~~~~~~~~~~~~~
~~~~~~~~~~
包含波浪线的代码
~~~~~~~~~~
~~~~~~~~~~~~~~~~

扩展：backtick_code_blocks

与 fenced_code_blocks 相同，但使用反引号（`）代替波浪线（~）.

扩展：fenced_code_attributes

可选地，您可以使用以下语法将属性附加到围栏或反引号代码块：

~~~~ {#mycode .haskell .numberLines startFrom="100"}
qsort []     = []
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
               qsort (filter (>= x) xs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

这里 mycode 是一个标识符， haskell 和 numberLines 是类，而 startFrom 是一个具有值 100 的属性。一些输出格式可以使用此信息进行语法高亮。目前，唯一使用此信息的输出格式是 HTML、LaTeX、Docx、Ms 和 PowerPoint。如果您的输出格式支持高亮显示和语言，则上面的代码块将以高亮显示出现，带有编号的行。（要查看支持哪些语言，请键入 pandoc --list-highlight-languages 。）否则，上面的代码块将如下所示：

<pre id="mycode" class="haskell numberLines" startFrom="100">
    <code>
    ...
    </code>
</pre>

numberLines（或 number-lines ）类将导致代码块的行被编号，从 1 或 startFrom 属性的值开始。 lineAnchors（或 line-anchors ）类将在 HTML 输出中使行成为可点击的锚点。

还可以使用快捷形式来指定代码块的语言：

```haskell
qsort [] = []
```

这等同于：

``` {.haskell}
qsort [] = []
```

此快捷形式可以与属性结合使用：

```haskell {.numberLines}
qsort [] = []
```

这相当于：

``` {.haskell .numberLines}
qsort [] = []
```

如果禁用了 fenced_code_attributes 扩展，但是输入包含代码块的类属性，则会在打开围栏后打印第一个类属性作为一个单独的词。

要阻止所有高亮显示，请使用 --no-highlight 标志。要设置高亮显示样式，请使用 --highlight-style 。对于更多有关高亮显示的信息，请参见下面的 语法高亮显示 。

行块

扩展: line_blocks

行块是由垂直线开头的一系列行( | ) 后跟一个空格。输出会保留对行的划分，并且任何前导空格也会被保留；否则，这些行会被格式化为 Markdown。这对诗和地址非常有用：

| 这首打油诗以解剖学的笑点
| 在非常经济的空间里打包。
| 但我见过的好诗
| 很少是干净的
| 干净的诗很少是搞笑的

| 200 Main St.
| Berkeley, CA 94718

如果需要的话，可以对行进行硬换行，但续行必须以空格开头。

| 尊敬的最可敬的且公正的塞缪尔·L.
常斯泰布尔, 小。
| 200 Main St.
| Berkeley, CA 94718

可以在内容中使用内联格式（如强调），但不能跨越行边界。不识别块级格式（如块引用或列表）。

此语法借鉴自 reStructuredText 。

列表

项目符号列表

项目符号列表是由一系列带项目符号的列表项组成的。带项目符号的列表项以项目符号开始 ( * , + , 或 - )。这里有一个简单的例子：

* 一
* 二
* 三

这会产生一个 “紧凑” 的列表。如果你想要一个 “宽松” 的列表，其中每个项目都按段落格式化，请在项目之间留出空行：

* 一

* 二

* 三

项目符号不必与左边界对齐；它们可以缩进一个、两个或三个空格。项目符号后面必须跟有空白字符。

如果后续行与第一行对齐（除去项目符号）会让列表项看起来更好：

* 这是我的第一个
  列表项。
* 和我的第二个。

但是 Markdown 也允许一种 “懒惰” 的格式：

* 这是我的第一个
  列表项。
* 和我的第二个。

在列表项中阻止内容

列表项可以包含多个段落和其他块级内容。但是，后续段落必须以空白行开头，并缩进到与列表标记后的第一个非空格内容对齐。

* 第一段落。

  继续。

* 第二段落。带有一个代码块，必须缩进
  八个空格：
  { 代码 }

例外：如果列表标记后跟一个缩进的代码块，则必须从列表标记开始五个空格之后，然后后续段落必须从列表标记的最后一个字符后开始两个列：

*     code

  continuation paragraph

列表项可以包括其他列表。在这种情况下，前导空白行是可选的。嵌套列表必须缩进以与包含列表项的列表标记后的第一个非空格字符对齐。

* fruits
  + apples
    - macintosh
    - red delicious
  + pears
  + peaches
* vegetables
  + broccoli
  + chard

如上所述，Markdown 允许您以“懒惰”的方式编写列表项，而不是缩进继续行。但是，如果有多个段落或其他块在列表项中，则每一项的第一行都必须缩进。

+ A lazy, lazy, list
  item.

+ Another one; this looks
  bad but is legal.

      Second paragraph of second

  list item.

有序列表

有序列表的工作原理就像项目符号列表一样，只是项目以枚举器而不是项目符号开头。

在原始 Markdown 中，枚举器是小数点和空格后面的十进制数字。数字本身被忽略，所以这个列表：

1.  one
2.  two
3.  three

和这个没有区别：

5.  one
7.  two
1.  three

扩展：fancy_lists

与原始 Markdown 不同，pandoc 允许使用大写和小写字母以及罗马数字，除了阿拉伯数字之外，还可以标记有序列表项。列表标记可以包含在括号中或后面跟着单个右括号或句点。它们必须与后面的文本之间至少有一个空格，如果列表标记是一个带有句点的大写字母，则至少有两个空格。

扩展 fancy_lists 还允许使用 # 作为有序列表标记代替数字：

#. one
#. two

注意：# 有序列表标记不适用于 commonmark 。

扩展：startnum

pandoc 还会注意使用的列表标记类型和起始编号，并尽可能在输出格式中保留这些信息。因此，下面的代码生成了一个列表，其中数字后面跟着一个右括号，从 9 开始，还有一个子列表，其中包含小写罗马数字：

9)  Ninth
10) Tenth
11) Eleventh
    i. subone
    ii. subtwo
    iii. subthree

Pandoc 在每次使用不同类型的列表标记时都会开始一个新的列表。因此，以下内容将创建三个列表：

(2) Two
(5) Three

1.  Four

* Five

如果需要默认的列表标记，请使用 #.：

#. one
#. two
#. three

扩展功能：task_lists

Pandoc 支持任务列表，使用 GitHub 风格 Markdown 的语法。

- [ ] 未完成的任务列表项
- [x] 已完成的项目

定义列表

扩展功能：definition_lists

Pandoc 支持定义列表，使用的是 PHP Markdown Extra 的语法，并进行了一些扩展。

Term 1

: Definition 1

Term 2 with _inline markup_

: Definition 2

        { some code, part of Definition 2 }

    Third paragraph of definition 2.

每个术语必须放在一行上，该行可以可选地后面跟着一个空行，并且必须跟着一个或多个定义。定义以冒号或波浪线开头，可以缩进一到两个空格。

一个术语可以有多个定义，每个定义可以由一个或多个块元素（段落、代码块、列表等）组成，每个块元素都缩进四个空格或一个制表符。定义主体（不包括第一行）应该缩进四个空格。但是，与其他 Markdown 列表一样，除了在段落或其他块元素的开头处，您可以“懒惰地”省略缩进：

Term 1

: Definition
with lazy continuation.

    定义的第二段。

如果您在定义前留出空间（如上面的例子所示），则定义的文本将被视为一个段落。在某些输出格式中，这意味着术语/定义对之间的间距会更大。为了获得更紧凑的定义列表，请省略定义前的空间：

Term 1
~ Definition 1

Term 2
~ Definition 2a
~ Definition 2b

请注意，定义列表中的项目之间需要留出空间。（可以通过 #compact_definition_lists 扩展来激活一个放宽此要求但不允许 “懒惰” 的硬换行的变体。）

编号示例列表

扩展功能：example_lists

特殊的列表标记 @ 可以用于按顺序编号的例子。第一个带有 @ 标记的列表项将被编号为 '1'，下一个为 '2'，以此类推，贯穿整个文档。编号的例子不必出现在同一个列表中；每个新的使用 @ 的列表将从上次停止的地方继续计数。因此，例如：

(@) 我的第一个例子将被编号为(1)。
(@) 我的第二个例子将被编号为(2)。

对例子的解释。

(@) 我的第三个例子将被编号为(3)。

可以给编号的例子添加标签，并在文档的其他地方引用它们：

(@good) 这是一个好的例子。

如(@good)所示，...

标签可以是任何包含字母数字字符、下划线或破折号的字符串。

例子列表中的延续段落必须始终缩进四个空格，无论列表标记的长度如何。也就是说，例子列表总是表现得好像设置了 four_space_rule 扩展一样。这是因为例子标签往往很长，而把内容缩进到标签后的第一个非空格字符会很别扭。

可以通过重复使用其标签来重复早期的编号例子：

(@foo) 示例句子。

中间的文本...

这个理论可以解释我们之前看到的情况（重复）：

(@foo) 示例句子。

但这只有在重复项单独位于列表中时才可靠，因为每个编号的例子列表都将从其起始编号连续编号。

结束列表

如果想在列表之后放置一个缩进的代码块，该怎么办？

- 第一项
- 第二项

  { 我的代码块 }

麻烦！在这里 pandoc（和其他 Markdown 实现工具）会将 { 我的代码块 } 视为第二项的第二段落，而不是代码块。

要“切断”第二项之后的列表，可以在其中插入一些不缩进的内容，如 HTML 注释，它不会在任何格式中产生可见输出：

- 第一项
- 第二项

<!-- 结束列表 -->

    { 我的代码块 }

如果你想要两个连续的列表而不是一个大的列表，也可以使用相同的技巧：

1.  一
2.  二
3.  三

<!-- -->

1.  uno
2.  dos
3.  tres

水平线

包含一行三个或更多 *，-，或 _ 字符（可选地用空格分隔）的行会产生一条水平线：

******
------

强烈建议水平线与周围文本之间用空白行隔开。如果水平线后面没有跟着空白行，pandoc 可能会尝试将后面的行解释为 YAML 元数据块或表格。

表格

可以使用四种类型的表格。前三种类型假设使用了等宽字体，如 Courier。第四种类型可以与比例字体一起使用，因为它不需要对齐列。

扩展: table_captions

可以选择性地为所有 4 种表格提供标题（如下面的例子所示）。标题是一个段落，以字符串 Table:（或 table: 或仅 :）开头，这部分将会被删除。它可以出现在表格之前或之后。

扩展: simple_tables

简单的表格看起来像这样：

  Right     Left     Center     Default
-------     ------ ----------   -------
     12     12        12            12
    123     123       123          123
      1     1          1             1

Table: 简单表格语法演示。

表头和表格行必须各自放在一行上。列对齐方式由表头文本相对于下方虚线的位置决定：

• 如果虚线在表头文本右侧对齐，但在左侧超出，则该列右对齐。
• 如果虚线在表头文本左侧对齐，但在右侧超出，则该列左对齐。
• 如果虚线在表头文本两侧均超出，则该列居中。
• 如果虚线在表头文本两侧对齐，则使用默认对齐方式（在大多数情况下，这将是左对齐）。

表格必须以空行结束，或者以虚线行后跟空行结束。

可以省略表头行，条件是使用虚线来结束表格。例如：

-------     ------ ----------   -------
     12     12        12             12
    123     123       123           123
      1     1          1              1
-------     ------ ----------   -------

当省略表头行时，列对齐方式基于表格正文的第一行。因此，在上面的表格中，列将分别右对齐、左对齐、居中和右对齐。

扩展: multiline_tables

多行表格允许表头和表格行跨越多行文本（但不支持跨越表格的多列或多行单元格）。这里有一个例子：

-------------------------------------------------------------
 Centered   Default           Right Left
  Header    Aligned         Aligned Aligned
----------- ------- --------------- -------------------------
   First    row                12.0 Example of a row that
                                    spans multiple lines.

  Second    row                 5.0 Here's another one. Note
                                    the blank line between
                                    rows.
-------------------------------------------------------------

Table: 这是标题。它也可以跨越
多行。

这些类似于简单表格，但有以下区别：

• 它们必须以虚线行开始，位于表头文本之前（除非省略了表头行）。
• 必须以虚线行，然后是一个空行结束。
• 行之间必须隔开空白行。

在多行表格中，表格解析器会注意到列宽，并且编写器尝试在输出中重现这些相对宽度。因此，如果你发现输出中的一列太窄，请尝试在 Markdown 源中加宽该列。

在多行表格和简单表格中都可以省略表头：

----------- ------- --------------- -------------------------
   First    row                12.0 Example of a row that
                                    spans multiple lines.

  Second    row                 5.0 Here's another one. Note
                                    the blank line between
                                    rows.
----------- ------- --------------- -------------------------

: Here's a multiline table without a header.

多行表格可能只有一行，但是该行后面应该跟着空白行（然后是结束表格的虚线行），否则可能会将其解释为简单表格。

扩展: grid_tables

网格表格看起来像这样：

: Sample grid table.

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+---------------+---------------+--------------------+

等号的一行将表头与表格主体分开，在不需要表头的表格中可以省略。网格表格的单元格可以包含任意的块元素（多个段落、代码块、列表等）。

单元格可以跨越多列或多行：

+---------------------+----------+
| Property            | Earth    |
+=============+=======+==========+
|             | min   | -89.2 °C |
| Temperature +-------+----------+
| 1961-1990   | mean  | 14 °C    |
|             +-------+----------+
|             | max   | 56.7 °C  |
+-------------+-------+----------+

一个表格的表头可以包含多于一行的内容：

+---------------------+-----------------------+
| Location            | Temperature 1961-1990 |
|                     | in degree Celsius     |
|                     +-------+-------+-------+
|                     | min   | mean  | max   |
+=====================+=======+=======+=======+
| Antarctica          | -89.2 | N/A   | 19.8  |
+---------------------+-------+-------+-------+
| Earth               | -89.2 | 14    | 56.7  |
+---------------------+-------+-------+-------+

对齐方式可以通过在表头之后的分隔线边界放置冒号来指定，就像处理管道表格那样：

+---------------+---------------+--------------------+
| Right         | Left          | Centered           |
+==============:+:==============+:==================:+
| Bananas       | $1.34         | built-in wrapper   |
+---------------+---------------+--------------------+

对于无表头的表格，冒号则放在顶部的那一行上：

+--------------:+:--------------+:------------------:+
| Right         | Left          | Centered           |
+---------------+---------------+--------------------+

通过使用等号 ( = ) 而不是破折号 ( - ) 来包围表格脚注的分隔线，可以定义表格的脚注：

 +---------------+---------------+
 | Fruit         | Price         |
 +===============+===============+
 | Bananas       | $1.34         |
 +---------------+---------------+
 | Oranges       | $2.10         |
 +===============+===============+
 | Sum           | $3.44         |
 +===============+===============+

脚注必须始终放置在表格的最底部。

可以轻松地使用 Emacs 的 table-mode（通过 M-x table-insert 命令）来创建网格表格。

扩展: pipe_tables

管道表格看起来像这样：

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

  : Demonstration of pipe table syntax.

语法与 PHP Markdown Extra 表格 相同。开头和结尾的管道字符是可选的，但在所有列之间都需要管道。冒号指示如上所示的列对齐方式。不能省略表头。要模拟无表头的表格，请包含带有空白单元格的表头。

由于管道指示列边界，因此列不必像上面示例中那样垂直对齐。因此，这是一个完全合法（虽然丑陋）的管道表格：

fruit| price
-----|-----:
apple|2.05
pear|1.37
orange|3.09

管道表格的单元格不能包含段落和列表等块元素，并且不能跨越多行。如果 Markdown 源代码的任何一行比列宽长（参见 --columns），则表格将占据整个文本宽度，单元格内容将换行，相对单元格宽度由表头与表格主体之间的分隔线中的破折号数量决定。（例如 ---|- 会使第一列占 3/4 的宽度，第二列占 1/4 的宽度。）另一方面，如果没有行比列宽更宽，则单元格内容不会被换行，并且单元格大小将根据其内容进行调整。

注意：pandoc 还识别如下形式的管道表格，就像 Emacs 的 orgtbl-mode 所产生的那样：

| One | Two   |
|-----+-------|
| my  | table |
| is  | nice  |

不同之处在于使用了 + 而不是 |。不支持其他 orgtbl 功能。特别是，需要像上面那样添加冒号以获得非默认的列对齐方式。

元数据块

扩展: pandoc_title_block

如果文件以标题块开始

% 标题
% 作者（用分号分隔）
% 日期

它将被解析为书目信息，而不是普通文本。（例如，在独立的 LaTeX 或 HTML 输出的标题中使用。）该块可以仅包含标题、标题和作者，或者所有三个元素。如果你想要包含一个作者但没有标题，或者标题和日期但没有作者，你需要一个空白行：

%
% 作者

% 我的标题
%
% 2006 年 6 月 15 日

标题可以占据多行，但是续行必须以前导空格开始，如下所示：

% 我的标题
占据多行

如果文档有多个作者，作者可以放在单独的行上，并以前导空格开始，或者用分号分隔，或者两者都用。因此，下面所有的都是等价的：

% 作者一
作者二

% 作者一; 作者二

% 作者一;
作者二

日期必须放在一行内。

所有三个元数据字段都可以包含标准内联格式化（斜体、链接、脚注等）。

标题块将始终被解析，但它们只在选择 --standalone (-s) 选项时才会影响输出。在 HTML 输出中，标题会出现两次：一次在文档头部---这是在浏览器窗口顶部出现的标题---另一次在文档主体的开头。文档头部的标题可以有一个可选的前缀附加 --title-prefix 或 -T 选项。文档主体中的标题显示为带有 "class" 属性为 "title" 的 H1 元素，因此可以通过 CSS 来抑制或重新格式化它。如果指定了标题前缀 -T 并且文档中没有标题块，则将仅使用标题前缀作为 HTML 标题。

man 页面编写器从标题行提取标题、man 页面部分编号和其他页眉和页脚信息。假设标题是标题行上的第一个单词，它可以在可选的括号中的（单个数字）部分编号结束。（标题和括号之间不应有空格。）之后的任何内容都被认为是额外的页脚和页眉文本。一个管道字符 ( | )应该用来分隔页脚文本和页眉文本。因此，

% PANDOC(1)

将生成一个标题为 PANDOC 和第 1 节的 man 页面。

% PANDOC(1) Pandoc 用户手册

还将在页脚中包含 "Pandoc用户手册"。

% PANDOC(1) Pandoc 用户手册 | 版本 4.0

还将在页眉中包含 "版本4.0"。

扩展功能: yaml_metadata_block

YAML 元数据块是一个有效的 YAML 对象，由顶部的三破折线 ( --- ) 行和底部的三破折线 ( --- )或三点 ( ... ) 行分隔。初始行 --- 后面不能跟空白行。YAML 元数据块可以在文档的任何位置出现，但如果不在开头，则必须由空白行分隔。

请注意，由于 pandoc 在提供多个输入文件时的方式连接它们，您也可以将元数据保存在一个单独的 YAML 文件中，并将其作为参数传递给 pandoc，与您的 Markdown 文件一起：

pandoc chap1.md chap2.md chap3.md metadata.yaml -s -o book.html

只要确保 YAML 文件以 --- 开始并以 --- 或 ... 结束即可。或者，您可以使用--metadata-file 选项。使用这种方法，您无法从主 Markdown 输入文档引用内容（如脚注）。

元数据将从 YAML 对象的字段中获取并添加到任何现有的文档元数据中。元数据可以包含列表和对象（任意嵌套），但是所有字符串标量都将被解释为 Markdown。以下划线结尾的字段名称将被 pandoc 忽略。 （它们可以被外部处理器赋予角色。）字段名称不得被解释为 YAML 数字或布尔值（因此，例如，yes，True 和 15 不能用作字段名称）。

文档可以包含多个元数据块。如果有两个元数据块试图设置相同的字段，则第二个块中的值将被采用。

每个元数据块在内部被处理为独立的 YAML 文档。这意味着，例如，一个块中定义的任何 YAML 锚点都不能在另一个块中引用。

当使用 pandoc 与 -t markdown 创建 Markdown 文档时，只有使用 -s/--standalone 选项时才会生成 YAML 元数据块。所有元数据都会出现在文档开头的单个块中。

请注意，必须遵循 YAML 转义规则。因此，例如，如果标题包含冒号，则必须用引号括起来，如果它包含反斜杠转义，则必须确保它不被视为 YAML 转义序列 。管道符号 ( | )可用于开始一个缩进块，该块将按原样解释，无需转义。当字段包含空白行或块级格式化时，需要此形式：

---
title:  '这是标题：它包含冒号'
author:
- 作者一
- 作者二
keywords: [nothing, nothingness]
abstract: |
这是摘要。

它由两段组成。
...

字面量块在 | 之后必须相对于包含 | 的行进行缩进。如果未进行缩进，YAML 将无效，pandoc 将不会将其解释为元数据。关于控制 YAML 的复杂规则的概述，请参阅 Wikipedia 上关于 YAML 语法的文章 。

模板变量会根据元数据自动设置。因此，例如，在编写 HTML 时，变量 abstract 将被设置为其 HTML 等价物，即 Markdown 中 abstract 字段的内容：

<p>This is the abstract.</p>
<p>It consists of two paragraphs.</p>

变量可以包含任意的 YAML 结构，但模板必须匹配这种结构。默认模板中的 author 变量期望一个简单的列表或字符串，但可以更改为支持更复杂的结构。例如，以下组合会在给出机构的情况下为作者添加机构：

---
title: 文档标题
author:
- name: 作者一
    affiliation: 某地大学
- name: 作者二
    affiliation: 无处大学
...

要使用上面示例中结构化的作者，您需要一个自定义模板：

$for(author)$
$if(author.name)$
$author.name$$if(author.affiliation)$ ($author.affiliation$)$endif$
$else$
$author$
$endif$
$endfor$

要在文档的头部指定原始内容，可以使用 header-includes；但是，重要的是要将此内容标记为特定输出格式的原始代码，使用 raw_attribute 扩展，否则它将被解释为 Markdown。例如：

header-includes:
  - |
    ```{=latex}
    \let\oldsection\section
    \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
    ```

注意：yaml_metadata_block 扩展与 commonmark 以及 markdown（并且在 gfm 和 commonmark_x 中默认启用）一起工作。然而，在这些格式中，以下限制适用：

• YAML 元数据块必须出现在文档的开头（并且只能有一个）。如果给 pandoc 提供了多个文件作为参数，只有第一个可以是 YAML 元数据块。

• YAML 结构的叶节点是独立解析的，彼此之间以及与文档的其余部分无关。因此，例如，如果您不能在这些上下文中使用引用链接，除非链接定义也在文档的其他地方。

反斜杠转义

扩展：all_symbols_escapable

除了在代码块或内联代码中，任何标点符号或空格字符，如果前面有反斜杠，则会被视为字面量，即使它通常表示格式化。因此，例如，如果您写入

\*\*hello\*\*

那么您将会得到

<em>*hello*</em>

而不是

<strong>hello</strong>

这个规则比原始 Markdown 的规则更容易记住，原始 Markdown 的规则只允许以下字符通过反斜杠转义：

\`*_{}[]()>#+-.!

（但是，如果使用 markdown_strict 格式，将使用原始 Markdown 的规则。）

反斜杠转义的空格被解析为非断行空格。在 TeX 输出中，它将出现为 \~`。在 HTML 和 XML 输出中，它将作为一个字面的 Unicode 非断行空格字符出现（请注意，它实际上将在生成的 HTML 源代码中看起来“不可见”；您仍然可以使用 --ascii 命令行选项使其以明确的实体形式出现）。

反斜杠转义的新行（即反斜杠出现在行尾）被解析为硬行断行。它将在 TeX 输出中出现为 \\，在 HTML 中为 <br />。这是 Markdown 表示硬行断行的一种很好的替代方法，该方法使用一行末尾的两个空格。

反斜杠转义在字面量上下文中不起作用。

内联格式化

强调

为了 强调 某些文本，可以用 * 或 _ 包围它，例如：

这段文本是 _用下划线强调的_, 而这段是 _用星号强调的_。

双 * 或 _ 可以产生 强烈强调:

这是 **强烈强调** 和 **用下划线强调**。

被空格包围的或被反斜杠转义的 * 或 _ 不会触发强调：

这里 _ 不会被强调 _, 而 \*这个也不会被强调\*。

扩展功能: intraword_underscores

因为 _ 有时会被用于单词和标识符中，所以 pandoc 不会将被字母数字字符包围的 _ 解释为强调标记。如果你想只强调单词的一部分，请使用 *：

feas*ible*, 而不是 feas*able*。

删除线

扩展功能: strikeout

要使用水平线删除一段文本，请在开头和结尾处使用 ~~。因此，例如，

这 ~~是被删除的文本。~~

上标和下标

扩展功能: superscript, subscript

上标可以通过将上标文本包围在 ^ 字符来书写；下标可以通过将下标文本包围在 ~ 字符来书写。例如，

H~2~O 是液体。 2^10^ 是 1024。

位于 ^...^ 或 ~...~ 之间的文本不能包含空格或换行。如果上标或下标文本包含空格，则必须用反斜杠进行转义。（这样做是为了防止通过普通使用 ~ 和 ^ 偶然产生上标和下标，以及避免与脚注产生不良交互。）因此，如果你想让字母 P 后跟 'a cat' 的下标，请使用 P~a\ cat~，而不是 P~a cat~ 。

原文引用

为了使一小段文本保持原文形式，请将其放在反引号内：

什么是 `>>=` 和 `>>` 之间的区别？

如果原始文本包含反引号，请使用双反引号：

这里有一个字面意义的反引号 `` ` ``。

（在开头的反引号和结尾的反引号前后的空格将会被忽略。）

一般规则是，一个字面意义的范围从连续的反引号开始（可选地后跟一个空格），并以相同数量的反引号结束（可选地前导一个空格）。

请注意，在字面意义的上下文中，反斜杠转义（和其他 Markdown 构造）不起作用：

这是一个反斜杠后跟一个星号: `\*`。

扩展: inline_code_attributes

可以像 围栏代码块 一样给字面意义的文本附加属性：

`<$>`{.haskell}

下划线

要给文本加下划线，请使用 [underline 类：

[Underline]{.underline}

或者，没有使用 bracketed_spans 扩展（但有 native_spans）：

<span class="underline">Underline</span>

这将在所有支持下划线的输出格式中工作。

小型大写字母

要写小型大写字母，请使用 smallcaps 类：

[Small caps]{.smallcaps}

或者，没有使用 bracketed_spans 扩展：

<span class="smallcaps">Small caps</span>

为了与其他 Markdown 版本兼容，也支持 CSS：

<span style="font-variant:small-caps;">Small caps</span>

这将在所有支持小型大写字母的输出格式中工作。

高亮显示

要高亮显示文本，请使用 mark 类：

[Mark]{.mark}

或者，没有使用 bracketed_spans 扩展（但有 native_spans）：

<span class="mark">Mark</span>

这将在所有支持高亮显示的输出格式中工作。

数学符号

扩展: tex_math_dollars

任何位于两个 $ 字符之间的内容都将被视为 TeX 数学表达式。开启的 $ 必须紧邻其右侧有一个非空格字符，而关闭的 $ 必须紧邻其左侧有一个非空格字符，并且不能立即跟在一个数字之后。因此，$20,000 and $30,000 不会被解析为数学表达式。如果出于某种原因你需要用实际的 $ 字符包围文本，可以通过反斜杠转义它们，这样它们就不会被视为数学分隔符。

对于展示数学表达式，请使用 $$ 分隔符。（在这种情况下，分隔符可以与公式之间有空白。但是，在开启和关闭的 $$ 分隔符之间不能有空行。）

TeX 数学将在所有输出格式中打印。如何渲染取决于输出格式：

• LaTeX

  它将以原样形式出现在 \(...\)（用于内联数学）或 \[...\]（用于展示数学）中。

• Markdown, Emacs Org 模式, ConTeXt, ZimWiki

  它将以原样形式出现在 $...$（用于内联数学）或 $$...$$（用于展示数学）中。

• XWiki

  它将以原样形式出现在 \{\{formula\}\}..\{\{/formula\}\} 中。

• reStructuredText

  将使用解释性文本角色 :math: 渲染它 (文档)。

• AsciiDoc

  对于 AsciiDoc 输出，数学将以原样形式出现在 latexmath:[...] 中。对于 asciidoc_legacy，括号内的材料也将包括内联或展示数学分隔符。

• Texinfo

  它将在 @math 命令内被渲染。

• roff man, Jira 标记

  它将被原样渲染，不带 $。

• MediaWiki, DokuWiki

  它将在 <math> 标签内被渲染。

• Textile

  它将在 <span class="math"> 标签内被渲染。

• RTF, OpenDocument

  如果可能，它将使用 Unicode 字符渲染，否则将以原样形式出现。

• ODT

  如果可能，它将使用 MathML 渲染。

• DocBook

  如果使用了 --mathml 选项，它将使用 MathML 在 inlineequation 或 informalequation 标签内渲染。否则，如果可能，将使用 Unicode 字符渲染。

• Docx 和 PowerPoint

  它将使用 OMML 数学标记渲染。

• FictionBook2

  如果使用了 --webtex 选项，公式将被渲染为图像，使用 CodeCogs 或其他兼容的 Web 服务下载并嵌入到电子书中。否则，将以原样形式出现。

• HTML, Slidy, DZSlides, S5, EPUB

  数学在 HTML 中的渲染方式将取决于所选的命令行选项。因此，请参阅 HTML 中的数学渲染。

原始 HTML

扩展: raw_html

Markdown 允许你在文档的任何位置插入原始 HTML（或 DocBook）（除字面值上下文外，其中 <, >, 和 & 被按字面意义解析）。从技术上讲这不是一个扩展，因为标准 Markdown 允许这样做，但它被当作一个扩展来处理以便需要时可以禁用。

原始 HTML 在 HTML、S5、Slidy、Slideous、DZSlides、EPUB、Markdown、CommonMark、Emacs Org 模式和 Textile 输出中不变地传递，而在其他格式中被抑制。

对于在 Markdown 文档中包含原始 HTML 的更明确的方法，请参见 raw_attribute 扩展 文档。

在 CommonMark 格式中，如果启用了 raw_html，上标、下标、删除线和小大写将以 HTML 表示。否则，将使用纯文本备选方案。请注意，即使禁用了 raw_html，如果表格无法使用管道符号表示，则仍将使用 HTML 语法渲染。

扩展: markdown_in_html_blocks

原始 Markdown 允许你包含 HTML “块”：位于平衡标签之间的 HTML 块，这些块通过空白行与周围文本分隔，并且在左边界开始和结束。在这些块内，所有内容都被解释为 HTML，而不是 Markdown；因此，例如，* 不表示强调。

当使用 markdown_strict 格式时，Pandoc 将按照这种方式处理；但默认情况下，Pandoc 将 HTML 块标签之间的内容解释为 Markdown。因此，例如，Pandoc 将把下面的内容转换为：

<table>
  <tr>
    <td>*one*</td>
    <td>[a link](https://google.com)</td>
  </tr>
</table>

插入

<table>
  <tr>
    <td><em>one</em></td>
    <td><a href="https://google.com">a link</a></td>
  </tr>
</table>

而 Markdown.pl 会保持其原样不变。

这一规则有一个例外：在 <script>、<style>、<pre> 和 <textarea> 标签之间的文本不会被解释为 Markdown。

这种与原始 Markdown 的不同之处应该使得混合使用 Markdown 和 HTML 块元素更加容易。例如，可以在不阻止其被解释为 Markdown 的情况下，用 <div> 标签包围一段 Markdown 文本。

扩展: native_divs

对 <div> 标签内的内容使用原生 pandoc Div 块。对于大多数部分这应该提供与 markdown_in_html_blocks 相同的输出，但它使编写 pandoc 过滤器来操作 块变得更容易。

扩展: native_spans

对 <span> 标签内的内容使用原生 pandoc Span 块。对于大多数部分这应该给出与 raw_html 相同的输出，但它使编写 PanDoc 过滤器来操作 内联变得更容易。

扩展: raw_tex

除了原始 HTML 外，pandoc 允许在文档中包含原始 LaTeX、TeX 和 ConTeXt。内联 TeX 命令将被保留，并且不变地传递给 LaTeX 和 ConTeXt 编写器。因此，例如，您可以使用 LaTeX 包含 BibTeX 引文：

这个结果在 \cite{jones.1967} 中得到证明。

请注意，在 LaTeX 环境中，例如

\begin{tabular}{|l|l|}\hline
Age & Frequency \\ \hline
18--25  & 15 \\
26--35  & 33 \\
36--45  & 22 \\ \hline
\end{tabular}

开始和结束标签之间的材料将被视为原始 LaTeX，而不是 Markdown。

有关在 Markdown 文档中以更明确和灵活的方式包含原始 TeX 的更多信息，请参阅 raw_attribute 扩展。

除 Markdown、LaTeX、Emacs Org 模式和 ConTeXt 之外的输出格式中会忽略内联 LaTeX。

通用原始属性

扩展: raw_attribute

具有特殊类型的属性的内联跨度和围栏代码块将被解析为指定格式的原始内容。例如，下面的示例产生一个原始 roff ms 块：

```{=ms}
.MYMACRO
blah blah

以下是转换后的简体中文 Markdown 格式的内容：

以下产生一个原始的 html 内联元素：

This is `<a>html</a>`{=html}

这可以用来在 docx 文档中插入原始的 XML，例如一个分页符：

```{=openxml}
<w:p>
  <w:r>
    <w:br w:type="page"/>
  </w:r>
</w:p>
```

格式名称应该与目标格式名称匹配（参见 -t/--to，以上，获取列表，或使用 pandoc --list-output-formats 。对于 docx 输出使用 openxml，对于 odt 输出使用 opendocument，对于 epub3 输出使用 html5，对于 epub2 输出使用 html4，对于 pdf 输出使用 latex、beamer、ms 或 html5（取决于你对 --pdf-engine 的设置）。

此扩展假设相关类型的内联代码或围栏代码块是启用的。因此，例如，要使用原始属性与反引号代码块，必须启用 backtick_code_blocks。

原始属性不能与常规属性结合使用。

LaTeX 宏

扩展：latex_macros

当启用此扩展时，pandoc 将解析 LaTeX 宏定义，并将产生的宏应用于所有 LaTeX 数学和原始 LaTeX。因此，例如，以下内容将在所有输出格式中工作，而不仅仅是 LaTeX：

\newcommand{\tuple}[1]{\langle #1 \rangle}

$\tuple{a, b, c}$

请注意，如果 LaTeX 宏出现在带有 raw_attribute 扩展标记的原始 span 或块中，则不会应用这些宏。

当禁用 latex_macros 时，原始 LaTeX 和数学将不会应用宏。当你针对 LaTeX 或 PDF 时，这通常是一个更好的方法。

LaTeX 中的宏定义仅在未启用 latex_macros 时作为原始 LaTeX 传递。无论是否启用了 latex_macros，Markdown 源（或其他允许 raw_tex 的格式）中的宏定义都将被传递。

链接

Markdown 允许以多种方式指定链接。

自动链接

如果你将 URL 或电子邮件地址放在尖括号中，它将成为一个链接：

<https://google.com>
<sam@green.eggs.ham>

内联链接

内联链接由方括号中的链接文本组成，后跟括号中的 URL（可选地，URL 可以后面跟着一个引号中的链接标题）。

这是一个 [内联链接](/url)，这里有一个带标题的链接：[点这里获得好时光](https://fsf.org "click here for a good time!")。

方括号部分和括号部分之间不能有空格。链接文本可以包含格式化（如强调），但标题不可以。

在行内链接中的电子邮件地址不会被自动检测到，因此必须使用 mailto 前缀：

[给我写信！](mailto:sam@green.eggs.ham)

引用链接

显式引用链接包含两部分：链接本身和链接定义，这些定义可以在文档的其他位置（在链接之前或之后）。

链接由方括号中的链接文本后跟一个方括号中的标签组成。（除非启用了 spaced_reference_links 扩展，否则两者之间不能有空格。）链接定义由带括号的标签、冒号和空格、URL 以及可选的链接标题组成，链接标题可以是引号或括号内的。标签不能解析为引用（假设启用了 citations 扩展）：引用优先于链接标签。

下面是一些例子：

[我的标签 1]: /foo/bar.html "我的标题，可选"
[我的标签 2]: /foo
[我的标签 3]: https://fsf.org "自由软件基金会"
[我的标签 4]: /bar#special "单引号内的标题"

URL 可以可选地被尖括号包围：

[我的标签 5]: http://foo.bar.baz

标题可以位于下一行：

[我的标签 3]: https://fsf.org "自由软件基金会"

请注意，链接标签不区分大小写。所以，这将会工作：

这是我的链接[FOO]

[Foo]: /bar/baz

在隐式引用链接中，第二对括号为空：

查看 [我的网站]。

[我的网站]: http://foo.bar.baz

注意

在 Markdown.pl 和大多数其他 Markdown 实现中，引用链接定义不能出现在嵌套结构中，例如列表项或块引用。Pandoc 取消了这个看似任意的限制。因此，以下内容在 Pandoc 中是有效的，但在大多数其他实现中则不是：

> 我的块[引用]。
>
> [引用]: /foo

扩展：shortcut_reference_links

在快捷引用链接中，可以完全省略第二对括号：

查看 [我的网站]。

[我的网站]: http://foo.bar.baz

内部链接

要链接到同一文档的另一个部分，请使用自动生成的标识符（参见 标题标识符 ）。例如：

查看 [简介](#introduction)。

或

查看[简介]。

[简介]: #introduction

目前支持 HTML 格式（包括 HTML 幻灯片演示和 EPUB）、LaTeX 和 ConTeXt 的内部链接。

图片

立即被 ! 前置的链接将被视为图片。链接文本将用作图片的替代文本：

![月亮](http://xxx.com/lalune.jpg "月球之旅")

![电影胶卷]

[电影胶卷]: http://xxx.com/movie.gif

扩展：implicit_figures

如果段落中只包含带有非空 alt 文本的图像，则该图像将被渲染为带标题的图。图像的 alt 文本将用作标题。

![这是标题](http://xxx.com/url/of/image.png)

输出格式决定了如何渲染它。某些输出格式（例如 RTF）尚不支持图。在这些格式中，您只会得到一个带有无标题的图像的段落。

如果您只需要一个常规的内联图像，请确保它不是段落中的唯一内容。一种方法是在图像后插入一个不可断开的空格：

![这不是一个图](http://xxx.com/url/of/image.png)\

请注意，在 reveal.js 幻灯片演示中，具有 r-stretch 类的段落中的图像将填满屏幕，并且将省略标题和 figure 标签。

扩展功能: link_attributes

可以在链接和图像上设置属性：

带有属性的内联 ![图像](http://xxx.com/foo.jpg){#id .class width=30 height=20px}
和带有属性的引用 ![图像][ref]。

[ref]: http://xxx.com/foo.jpg "可选标题" {#id .class key=val key2="val 2"}

(当仅使用 #id 和 .class 时，此语法与 PHP Markdown Extra 兼容。)

对于 HTML 和 EPUB，除了 width 和 height（但包括 srcset 和 sizes）之外的所有已知 HTML5 属性都将按原样传递。未知属性将作为自定义属性传递，并在前面加上 data-。其他写入器会忽略其输出格式不特别支持的属性。

图像上的 width 和 height 属性具有特殊处理。如果没有单位，则假设单位是像素。但是，可以使用以下任何单位标识符：px、cm、mm、in、inch 和 %。数字和单位之间不应有任何空格。例如：

![](http://xxx.com/file.jpg){width=50%}

• 尺寸可能会转换为与输出格式兼容的形式（例如，以像素给出的尺寸在将 HTML 转换为 LaTeX 时将转换为英寸）。像素与物理测量之间的转换受 --dpi 选项的影响（默认情况下，假设 dpi 为 96，除非图像本身包含 dpi 信息）。
• 对于 % 单位，通常是相对于可用空间的。例如上面的例子将会渲染为以下内容。
  • HTML: <img href="file.jpg" style="width: 50%;" />
  • LaTeX: \includegraphics[width=0.5\textwidth,height=\textheight]{file.jpg}（如果您正在使用自定义模板，则需要像默认模板那样配置 graphicx。）
  • ConTeXt: \externalfigure[file.jpg][width=0.5\textwidth]
• 某些输出格式有一个类 ( ConTeXt ) 或一个唯一标识符（LaTeX \caption），或两者 (HTML)。
• 当没有指定 width 或 height 属性时，回退到查看图像分辨率和图像文件中嵌入的 dpi 元数据。

Div 和 Span

使用 native_divs 和 native_spans 扩展（参见 以上 ），HTML 语法可以用作 Markdown 的一部分来创建原生的 Div 和 Span 元素在 pandoc AST 中（而不是原始 HTML）。但是，也有更友好的语法可用：

扩展功能: fenced_divs

允许使用特殊的围栏语法来创建原生的 Div 块。一个 Div 由至少三个连续冒号及一些属性开始。属性后可选择性地跟另一个连续的冒号串。

注意: commonmark 解析器不允许属性后的冒号。

属性语法与围栏代码块中的语法完全相同（参见 扩展：fenced_code_attributes ）。与围栏代码块一样，可以使用大括号中的属性或单个未加括号的单词，后者将被视为类名。 Div 以另一行包含至少三个连续冒号的字符串结束。围栏 Div 应通过空白行与前后的块分隔。

示例：

::::: {#special .sidebar}
Here is a paragraph.

And another.
:::::

可以嵌套围栏划分。打开围栏之所以与众不同是因为它们必须具有属性：

::: Warning ::::::
This is a warning.

::: Danger
This is a warning within a warning.
:::
::::::::::::::::::

没有属性的围栏始终是关闭围栏。与围栏代码块不同，关闭围栏中的冒号数量不必匹配开头围栏中的数量。但是，为了视觉清晰起见，使用不同长度的围栏来区分嵌套划分与其父项是有帮助的。

扩展: bracketed_spans

括起来的内联序列，就像开始链接时会使用的一样，如果紧接着就是属性，则会被视为带有属性的 Span：

[这是一个 *一些文本*]{.class key="val"}

脚注

扩展: footnotes

Pandoc 的 Markdown 允许脚注，使用以下语法：

Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote.
[^longnote]: Here's one with multiple blocks.

    Subsequent paragraphs are indented to show that they
    belong to the previous footnote.

        { some.code }

    The whole paragraph can be indented, or just the first
    line. In this way, multi-paragraph footnotes work like
    multi-paragraph list items.

This paragraph won't be part of the note, because it
isn't indented.

脚注引用中的标识符不能包含空格、制表符、换行符或字符 ^，[ 或 ]。这些标识符仅用于关联脚注引用和注释本身；在输出中，脚注将按顺序编号。

脚注本身不必放在文档的末尾。它们可以出现在任何地方，但不能在其他块元素（列表，块引用、表格等）内部。每个脚注应该与其他周围内容（包括其他脚注）隔开空白行。

扩展: inline_notes(#extension-inline_notes)

也允许内联脚注（尽管与常规注释不同，它们不能包含多个段落）。语法如下：

这是一个内联注释。^[内联注释更容易编写，因为您不必选择一个标识符并向下移动以键入注释。]

内联和常规脚注可以自由混合。

引用语法

扩展: citations

为了引用带有标识符 foo 的书目项，请使用如下语法 @foo。正常的引用应包含在方括号中，不同的项目之间用分号隔开：

Blah blah [@doe99; @smith2000; @smith2004].

渲染方式取决于引用样式。对于作者-日期样式，可能会呈现为

    Blah blah (Doe 1999, Smith 2000, 2004).

对于脚注样式，可能会呈现为

Blah blah.[^1]

[^1]:
    John Doe, "Frogs," _Journal of Amphibians_ 44 (1999);
    Susan Smith, "Flies," _Journal of Insects_ (2000);
    Susan Smith, "Bees," _Journal of Insects_ (2004).

有关 CSL 样式的更多信息及其如何影响渲染效果，请参阅 CSL 用户文档。

除非引用键以字母、数字或 _ 开头，并且只包含字母数字和单个内部标点符号 ( :.#$%&-+?<>~/ )，否则必须用大括号包围，这些大括号不被视为键的一部分。在 @Foo_bar.baz. 中，键是 Foo_bar.baz，因为最终的句点不是内部标点，因此它不包含在键中。在 @{Foo_bar.baz.} 中，键是 Foo_bar.baz.，包括最终的句点。在 @Foo_bar--baz 中，键是 Foo_bar，因为重复的内部标点字符终止了键。如果使用 URL 作为键，则推荐使用大括号：[@{https://example.com/bib?name=foobar&date=2000}, p. 33]。

引用项可选地包括前缀、定位器和后缀。在

Blah blah [see @doe99, pp. 33-35 and *passim*; @smith04, chap. 1].

第一个项 ( doe99 ) 具有前缀 see、定位器 pp. 33-35 和后缀 and *passim*。第二个项 (smith04) 具有定位器 chap. 1 并没有前缀或后缀。

Pandoc 使用一些启发式方法来将定位器与主题的其余部分分开。它对 CSL 地域文件 中定义的定位器术语敏感。接受缩写形式或未缩写形式。在 en-US 地域中，定位器术语可以使用单数或复数形式，例如 book，bk./bks.; chapter,chap./chaps.; column,col./cols.; figure, fig./figs.; folio, fol./fols.; number, no./nos.; line, l./ll.; note, n./nn.; opus, op./opp.; page, p./pp.; paragraph, para./paras.; part, pt./pts.; section, sec./secs.; sub verbo, s.v./s.vv.; verse, v./vv.; volume, vol./vols.; ¶/¶¶; §/§§。如果没有使用定位器术语，则假设为 “page”。

在复杂的情况下，可以通过将定位器括在大括号中来强制将其视为定位器，或者通过在定位器前添加大括号来防止将后缀解析为定位器：

[@smith{ii, A, D-Z}, with a suffix]
[@smith, {pp. iv, vi-xi, (xv)-(xvii)} with suffix here]
[@smith{}, 99 years later]

减号 (-) 在 @ 之前会阻止在引用中提及作者。当作者已经在文中提到时，这可能很有用：

Smith 说 blah [-@smith04].

你也可以写一个作者在文中的引用，通过省略方括号：

@smith04 说 blah.

@smith04 [p. 33] 说 blah.

这将导致作者的名字被渲染，然后是书目详细信息。当你希望使引用成为句子的主题时，请使用此形式。

当你使用注释样式时，通常最好让 citeproc 从引用创建脚注，而不是编写显式注释。如果你确实写了一个包含引用的显式注释，请注意正常的引用将放在括号中，而作者在文中的引用则不会。出于这个原因，在使用注释样式时，有时更倾向于在注释中使用作者在文中的样式。

非默认扩展

以下 Markdown 语法扩展默认情况下在 pandoc 中未启用，但可以通过在格式名称后添加 +EXTENSION 来启用，其中 EXTENSION 是扩展的名称。因此，例如，markdown+hard_line_breaks 是带有硬换行的 Markdown。

扩展：rebase_relative_paths

根据包含链接或图像链接的文件路径重写 Markdown 链接和图像的相对路径。对于每个链接或图像，pandoc 将计算包含文件所在的目录，相对于工作目录，并将生成的路径附加到链接或图像路径上。

该扩展的使用最好通过示例来理解。假设你有一个用于书籍每章的子目录，chap1、chap2、chap3。每个都包含一个文件 text.md 和一系列章节中使用的图像。你希望 ![image](http://xx.com/spider.jpg) 在 chap1/text.md 中指代 chap1/spider.jpg 并且 ![image](http://xx.com/spider.jpg) 在 chap2/text.md 中指代 chap2/spider.jpg。为此，请使用

pandoc chap*/*.md -f markdown+rebase_relative_paths

无需此扩展，您将不得不使用 ![image](http://xx.com/chap1/spider.jpg) 在 chap1/text.md 和 ![image](http://xx.com/chap2/spider.jpg) 在 chap2/text.md。具有相对路径的链接将以与图像相同的方式重写。

绝对路径和 URL 不会更改。空路径或仅由片段组成的路径（例如，#foo）也不会更改。

注意

如果参考链接定义与引用链接或图像本身不同，则相对路径中的参考链接和图像将根据包含链接引用定义的文件进行重写，而不是根据包含引用链接或图像本身的文件进行重写。

扩展: mark

要突出显示一段文本，请使用 == 开始和结束。因此，例如，

这 ==是删除的文本。==

扩展: attributes

在解析 commonmark 时，允许将属性附加到任何内联或块级元素。属性的语法与 header_attributes 中使用的相同。

• 紧跟在内联元素后面的属性会影响该元素。如果它们跟在一个空格后，那么它们属于该空格。（因此，此选项涵盖了inline_code_attributes 和 link_attributes。）
• 紧跟在块元素之前的属性，单独位于一行，会影响该元素。
• 可以使用连续的属性指定符，无论是对于块还是内联。它们的属性将被合并。
• 在 Setext 或 ATX 标题文本末尾出现的属性（与文本通过空白分开）会影响标题元素。 （因此，此选项涵盖了 header_attributes。）
• 围栏代码块开头后的属性会影响代码块元素。（因此，此选项涵盖了 fenced_code_attributes。）
• 出现在参考链接定义末尾的属性会影响指向该定义的链接。

请注意，pandoc 的 AST 目前不允许将属性附加到任意元素。因此，如果需要，将添加 Span 或 Div 容器。

扩展: old_dashes

选择 pandoc <= 1.8.2.1 的行为来解析智能破折号：- 在数字前是一个破折号，而 -- 是一个长破折号。此选项只有在启用了 smart 的情况下才有效。对于 textile 输入，此选项会自动选择。

扩展: angle_brackets_escapable

允许使用反斜杠转义 < 和 >，就像在 GitHub 风格的 Markdown 中那样，但原始 Markdown 中不支持。这是 pandoc 默认的 all_symbols_escapable 的含义。

扩展: lists_without_preceding_blankline

允许列表紧随段落之后，中间没有空白空间。

扩展: four_space_rule

选择 pandoc <= 2.0 的列表解析行为，因此需要四个空格缩进来继续列表项段落。

扩展: spaced_reference_links

允许在引用链接的两个组件之间有空白，例如，

[foo] [bar].

扩展: hard_line_breaks

使段落内的所有换行符被解释为硬换行，而不是空格。

扩展: ignore_line_breaks

使段落内的换行符被忽略，而不是被视为空格或硬换行。此选项适用于东亚语言，在这些语言中，单词间不使用空格，而是为了易读性而将文本分隔成多行。

扩展: east_asian_line_breaks

当两个东亚宽字符之间出现换行时，使段落内的换行被忽略，而不是被视为空格或硬换行。对于包含混合东亚宽字符和其他字符的文本，这是比 ignore_line_breaks 更好的选择。

扩展: emoji

将文本表情符号如 :smile: 解析为 Unicode 表情符号。

扩展: tex_math_gfm

支持两种 GitHub 特定的数学格式。内联数学：$`e=mc^2`$。

显示数学：

``` math
e=mc^2
```

扩展: tex_math_single_backslash

使位于 \( 和 \) 之间的任何内容被解释为内联 TeX 数学，位于 \[ 和 \] 之间的任何内容被解释为显示 TeX 数学。注意：此扩展的一个缺点是它排除了对 ( 和 [ 的转义。 ]

扩展: tex_math_double_backslash

使得位于 \\( 和 \\) 之间的任何内容被解释为内联 TeX 数学，位于 \\[ 和 \\] 之间的任何内容被解释为显示 TeX 数学。

扩展: markdown_attribute

默认情况下，pandoc 将块级标签内的材料解释为 Markdown。此扩展改变了行为，使得仅当标签具有 markdown=1 属性时才在块级标签内解析 Markdown。

扩展: mmd_title_block

启用文档顶部的 MultiMarkdown 样式标题块，例如：

Title: 我的标题
Author: John Doe
Date: September 1, 2008
Comment: 这是一个样本 mmd 标题块，带有
跨多行的字段。

请参阅 MultiMarkdown 文档以获取详细信息。如果启用了 pandoc_title_block 或 yaml_metadata_block，它将优先于 mmd_title_block。

扩展: abbreviations

解析 PHP Markdown Extra 缩写键，如

\*[HTML]: Hypertext Markup Language

请注意，pandoc 文档模型不支持缩写，因此如果启用此扩展，则会忽略缩写键（而不是将其解析为段落）。

扩展: alerts

支持 GitHub 风格 Markdown 警告， 如

> [!TIP]
> 对于更好地或更轻松地做事的有益建议。

扩展: autolink_bare_uris

即使绝对 URI 没有被尖括号 <...> 包围，也将其转换为链接。

扩展: mmd_link_attributes

解析 MultiMarkdown 风格的链接和图片引用上的键值属性。此扩展不应与 link_attributes 扩展混淆。

这是一个带有 MultiMarkdown 属性的引用 ![image][ref]。

[ref]: https://path.to/image "Image title" width=20px height=30px
id=myId class="myClass1 myClass2"

扩展: mmd_header_identifiers

解析 MultiMarkdown 风格的标题标识符（方括号内，在标题之后但在 ATX 标题中的任何尾部 # 之前）。

扩展: compact_definition_lists

激活 pandoc 1.12.x 及更早版本的定义列表语法。此语法在多个方面与上文 定义列表 中描述的不同：

• 定义列表的连续项之间不需要空白行。
• 若要获得“紧密”或“紧凑”的列表，省略连续项之间的空间；术语与其定义之间的空间不影响任何内容。
• 不允许懒惰地换行段落：整个定义必须缩进四个空格。^4^

扩展: gutenberg

使用 Project Gutenberg 为 plain 输出约定：全部大写表示强烈强调，周围用下划线表示常规强调，在标题周围添加额外的空白空间。

扩展: sourcepos

解析 commonmark 时包含源位置属性。对于可以接受属性的元素，添加了一个 data-pos 属性；其他元素被放置在一个具有 data-pos 属性的包围 Div 或 Span 元素中。

扩展: short_subsuperscripts

解析 MultiMarkdown 风格的上标和下标，它们以 '~' 或 '^' 字符开始，并包括其后的字母数字序列。例如：

x^2 = 4

或者

氧气是 O~2。

扩展: wikilinks_title_after_pipe

无论标题是在管道符号之前还是之后，pandoc 都支持多种 Markdown 维基链接语法。

使用 --from=markdown+wikilinks_title_after_pipe 结果为

[[URL|title]]

在使用 --from=markdown+wikilinks_title_before_pipe 时，结果为

[[title|URL]]

Markdown 变体

除 Pandoc 扩展的 Markdown 外，还支持以下 Markdown 变体：

• markdown_phpextra（PHP Markdown Extra）
• markdown_github（已弃用的 GitHub 风格 Markdown）
• markdown_mmd（MultiMarkdown）
• markdown_strict（Markdown.pl）
• commonmark（CommonMark）
• gfm（Github 风格 Markdown）
• commonmark_x（具有许多 Pandoc 扩展的 CommonMark）

要查看给定格式支持哪些扩展以及哪些默认启用，可以使用命令

pandoc --list-extensions=FORMAT

其中将 FORMAT 替换为格式的名称。

请注意，commonmark、gfm 和 commonmark_x 的扩展列表是相对于默认的 CommonMark 定义的。因此，例如，backtick_code_blocks 不会作为扩展出现，因为它默认启用且无法禁用。