注释

序列 $-- 和行尾之间的任何内容都将被视为注释并从输出中省略。

分隔符

为了在模板中标记变量和控制结构，可以使用 $…$ 或 ${…} 作为分隔符。同个模板中也可以混合使用这些样式，但开闭分隔符必须在每种情况下匹配。开分隔符后面可以跟一个或多个空格或制表符，这些将被忽略。闭分隔符前面可以跟一个或多个空格或制表符，这些将被忽略。

要在文档中包含字面量 $，请使用 $$。

插值变量

插值变量的槽位是被匹配分隔符包围的变量名。变量名必须以字母开头，可以包含字母、数字、_、- 和 .。关键字 it、if、else、endif、for、sep 和 endfor 不能用作变量名。示例：

$foo$
$foo.bar.baz$
$foo_bar.baz-bim$
$ foo $
${foo}
${foo.bar.baz}
${foo_bar.baz-bim}
${ foo }

带点的变量名用于获取结构化变量值。例如，employee.salary 将返回作为 employee 字段值的对象的 salary 字段的值。

• 如果变量的值是简单值，它将按原样渲染。（请注意，不进行转义；假定调用程序将根据输出格式适当地转义字符串。）
• 如果值是列表，则这些值将连接起来。
• 如果值是映射，则将渲染字符串 true。
• 所有其他值都将渲染为空字符串。

条件语句

条件语句以 if(variable)（括在匹配的分隔符中）开始，以 endif（括在匹配的分隔符中）结束。它可以选择包含一个 else（括在匹配的分隔符中）。如果 variable 具有真值，则使用 if 部分，否则使用 else 部分（如果存在）。以下值被视为真：

• 任何映射
• 任何包含至少一个真值的数组
• 任何非空字符串
• 布尔真

请注意，在 YAML 元数据（以及使用 -M/--metadata 在命令行上指定的元数据）中，未引用的 true 和 false 将被解释为布尔值。但是，使用 -V/--variable 在命令行上指定的变量将始终被赋予字符串值。因此，如果您使用 -V foo=false，条件 if(foo) 将被触发，但如果您使用 -M foo=false，则不会。

示例

$if(foo)$bar$endif$

$if(foo)$
  $foo$
$endif$

$if(foo)$
part one
$else$
part two
$endif$

${if(foo)}bar${endif}

${if(foo)}
  ${foo}
${endif}

${if(foo)}
${ foo.bar }
${else}
no foo!
${endif}

关键字 elseif 可用于简化复杂的嵌套条件语句：

$if(foo)$
XXX
$elseif(bar)$
YYY
$else$
ZZZ
$endif$

for 循环

for 循环以 for(variable)（括在匹配的分隔符中）开始，以 endfor（括在匹配的分隔符中）结束。

• 如果 variable 是一个数组，则循环内部的材料将重复评估，variable 依次设置为数组的每个值，并连接起来。
• 如果 variable 是一个映射，则内部的材料将设置为该映射。
• 如果关联变量的值不是数组或映射，则将对其值执行单次迭代。

示例

$for(foo)$$foo$$sep$, $endfor$

$for(foo)$
  - $foo.last$, $foo.first$
$endfor$

${ for(foo.bar) }
  - ${ foo.bar.last }, ${ foo.bar.first }
${ endfor }

$for(mymap)$
$it.name$: $it.office$
$endfor$

您可以选择使用 sep（括在匹配的分隔符中）在连续值之间指定分隔符。sep 和 endfor 之间的材料是分隔符。

${ for(foo) }${ foo }${ sep }, ${ endfor }

在循环内部，可以使用特殊的指示性关键字 it 来代替 variable。

${ for(foo.bar) }
  - ${ it.last }, ${ it.first }
${ endfor }

局部模板

局部模板（存储在不同文件中的子模板）可以通过使用局部模板的名称，后跟 () 来包含，例如：

${ styles() }

局部模板将在包含主模板的目录中查找。如果文件名没有扩展名，则假定其具有与主模板相同的扩展名。调用局部模板时，也可以使用包含文件扩展名的完整名称：

${ styles.html() }

（如果在模板目录中找不到局部模板，并且模板路径是相对路径，它还将在用户数据目录的 templates 子目录中查找。）

局部模板可以选择使用冒号应用于变量：

${ date:fancy() }

${ articles:bibentry() }

如果 articles 是一个数组，这将遍历其值，将局部模板 bibentry() 应用于每个值。因此，上面的第二个示例等同于：

${ for(articles) }
${ it:bibentry() }
${ endfor }

请注意，在遍历局部模板时必须使用指示性关键字 it。在上述示例中，bibentry 局部模板应包含 it.title（等等）而不是 articles.title。

包含的局部模板中会省略末尾的换行符。

局部模板可以包含其他局部模板。

数组值之间的分隔符可以用方括号指定，紧跟在变量名或局部模板之后：

${months[, ]}

${articles:bibentry()[; ]}

在这种情况下，分隔符是字面量（与显式 for 循环中的 sep 不同），不能包含插值变量或其他模板指令。

嵌套

为确保内容“嵌套”，即后续行缩进，请使用 ^ 指令：

$item.number$  $^$$item.description$ ($item.price$)

在此示例中，如果 item.description 有多行，它们都将缩进以与第一行对齐：

00123  A fine bottle of 18-year old
       Oban whiskey. ($148)

要将多行嵌套到同一级别，请在模板中将它们与 ^ 指令对齐。例如：

$item.number$  $^$$item.description$ ($item.price$)
               (Available til $item.sellby$.)

将产生：

00123  A fine bottle of 18-year old
       Oban whiskey. ($148)
       (Available til March 30, 2020.)

如果一个变量单独出现在一行上，前面有空白字符，并且同一行上没有其他文本或指令，并且变量的值包含多行，它将自动嵌套。

可断行空格

通常，模板中的空格（与插值变量的值相反）是不可断行的，但它们可以通过使用 ~ 关键字（以另一个 ~ 结束）在模板的一部分中变为可断行。

$~$This long line may break if the document is rendered
with a short line length.$~$

管道

管道转换变量或局部变量的值。管道使用斜杠（/）在变量名（或局部变量）和管道名之间指定。示例：

$for(name)$
$name/uppercase$
$endfor$

$for(metadata/pairs)$
- $it.key$: $it.value$
$endfor$

$employee:name()/uppercase$

管道可以链式调用：

$for(employees/pairs)$
$it.key/alpha/uppercase$. $it.name$
$endfor$

一些管道接受参数：

|----------------------|------------|
$for(employee)$
$it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
$endfor$
|----------------------|------------|

目前预定义了以下管道：

• pairs：将映射或数组转换为映射数组，每个映射具有 key 和 value 字段。如果原始值是数组，则 key 将是数组索引，从 1 开始。

• uppercase：将文本转换为大写。

• lowercase：将文本转换为小写。

• length：返回值的长度：文本值为字符数，映射或数组为元素数。

• reverse：反转文本值或数组，对其他值无效。

• first：如果应用于非空数组，则返回数组的第一个值；否则返回原始值。

• last：如果应用于非空数组，则返回数组的最后一个值；否则返回原始值。

• rest：如果应用于非空数组，则返回数组中除第一个值之外的所有值；否则返回原始值。

• allbutlast：如果应用于非空数组，则返回数组中除最后一个值之外的所有值；否则返回原始值。

• chomp：移除尾随的换行符（和可断行空格）。

• nowrap：禁用可断行空格上的换行。

• alpha：将可读作整数的文本值转换为小写字母 a..z（模 26）。这可用于从数组索引获取字母枚举。要获取大写字母，请与 uppercase 链式调用。

• roman：将可读作整数的文本值转换为小写罗马数字。这可用于从数组索引获取字母枚举。要获取大写罗马数字，请与 uppercase 链式调用。

• left n "leftborder" "rightborder"：以宽度 n 的块形式渲染文本值，左对齐，可选带左边框和右边框。对其他值无效。这可用于在表格中对齐材料。宽度是正整数，表示字符数。边框是双引号内的字符串；字面量 " 和 \ 字符必须进行反斜杠转义。

• right n "leftborder" "rightborder"：以宽度 n 的块形式渲染文本值，右对齐，对其他值无效。

• center n "leftborder" "rightborder"：以宽度 n 的块形式渲染文本值，居中对齐，对其他值无效。

元数据变量

title, author, date

允许识别文档的基本方面。通过 LaTeX 和 ConTeXt 包含在 PDF 元数据中。这些可以通过 pandoc 标题块（允许多个作者）或 YAML 元数据块 设置。

---
author:
- Aristotle
- Peter Abelard
...

请注意，如果您只想设置 PDF 或 HTML 元数据，而不在文档本身包含标题块，则可以设置 title-meta、author-meta 和 date-meta 变量。（默认情况下，这些变量会根据 title、author 和 date 自动设置。）HTML 中的页面标题由 pagetitle 设置，默认情况下它等于 title。

subtitle

文档副标题，包含在 HTML、EPUB、LaTeX、ConTeXt 和 docx 文档中

abstract

文档摘要，包含在 HTML、LaTeX、ConTeXt、AsciiDoc 和 docx 文档中

abstract-title

摘要标题，目前仅用于 HTML、EPUB 和 docx。这会自动设置为本地化值，取决于 lang，但可以手动覆盖。

keywords

要包含在 HTML、PDF、ODT、pptx、docx 和 AsciiDoc 元数据中的关键词列表；重复方式与上述 author 相同

subject

文档主题，包含在 ODT、PDF、docx、EPUB 和 pptx 元数据中

description

文档描述，包含在 ODT、docx 和 pptx 元数据中。某些应用程序将其显示为 Comments 元数据。

category

文档类别，包含在 docx 和 pptx 元数据中

此外，任何未包含在 ODT、docx 或 pptx 元数据中的根级字符串元数据都将作为自定义属性添加。例如，以下 YAML 元数据块：

---
title:  'This is the title'
subtitle: "This is the subtitle"
author:
- Author One
- Author Two
description: |
    This is a long
    description.

    It consists of two paragraphs
...

在转换为 docx、ODT 或 pptx 时，将包含 title、author 和 description 作为标准文档属性，并将 subtitle 作为自定义属性。

语言变量

lang

使用 IETF 语言标签（遵循 BCP 47 标准），例如 en 或 en-GB，标识文档的主要语言。语言子标签查找 工具可以查找或验证这些标签。这会影响大多数格式，并在使用 LaTeX（通过 babel 和 polyglossia）或 ConTeXt 时控制 PDF 输出中的断字。

使用带有 lang 属性的原生 pandoc Divs 和 Spans 来切换语言：

---
lang: en-GB
...

Text in the main document language (British English).

::: {lang=fr-CA}
> Cette citation est écrite en français canadien.
:::

More text in English. ['Zitat auf Deutsch.']{lang=de}

dir

基本脚本方向，可以是 rtl（从右到左）或 ltr（从左到右）。

对于双向文档，带有 dir 属性（值 rtl 或 ltr）的原生 pandoc span 和 div 可用于在某些输出格式中覆盖基本方向。如果最终渲染器（例如，生成 HTML 时的浏览器）支持 Unicode 双向算法，这可能并非总是必要的。

在使用 LaTeX 处理双向文档时，仅完全支持 xelatex 引擎（使用 --pdf-engine=xelatex）。

HTML 变量

document-css

启用在 styles.html 局部模板 中包含大部分 CSS（可以使用 pandoc --print-default-data-file=templates/styles.html 查看）。除非您使用 --css，否则此变量默认设置为 true。您可以通过例如 pandoc -M document-css=false 禁用它。

mainfont

设置 html 元素的 CSS font-family 属性。

fontsize

设置基本 CSS font-size，通常将其设置为例如 20px，但它也接受 pt（大多数浏览器中 12pt = 16px）。

fontcolor

设置 html 元素的 CSS color 属性。

linkcolor

设置所有链接的 CSS color 属性。

monofont

设置 code 元素的 CSS font-family 属性。

monobackgroundcolor

设置 code 元素的 CSS background-color 属性并添加额外填充。

linestretch

设置 html 元素的 CSS line-height 属性，最好是无单位的。

maxwidth

设置 CSS max-width 属性（默认值为 36em）。

backgroundcolor

设置 html 元素的 CSS background-color 属性。

margin-left, margin-right, margin-top, margin-bottom

设置 body 元素对应的 CSS padding 属性。

要为单个文档覆盖或扩展某些 CSS，例如包含：

---
header-includes: |
  <style>
  blockquote {
    font-style: italic;
  }
  tr.even {
    background-color: #f0f0f0;
  }
  td, th {
    padding: 0.5em 2em 0.5em 0.5em;
  }
  tbody {
    border-bottom: none;
  }
  </style>
---

HTML 数学变量

classoption

当使用 --katex 时，您可以使用 YAML 元数据 或 -M classoption=fleqn 将显示数学方程左对齐渲染。

HTML 幻灯片变量

这些变量影响 使用 pandoc 制作幻灯片 时的 HTML 输出。

institute

作者单位：多作者时可为列表

revealjs-url

reveal.js 文档的基本 URL（默认为 https://unpkg.com/reveal.js@^5）

s5-url

S5 文档的基本 URL（默认为 s5/default）

slidy-url

Slidy 文档的基本 URL（默认为 https://www.w3.org/Talks/Tools/Slidy2）

slideous-url

Slideous 文档的基本 URL（默认为 slideous）

title-slide-attributes

reveal.js 幻灯片标题页的额外属性。有关示例，请参见 reveal.js、beamer 和 pptx 中的背景。

所有 reveal.js 配置选项 都可以作为变量使用。要关闭 reveal.js 中默认为真的布尔标志，请使用 0。

Beamer 幻灯片变量

这些变量改变使用 beamer 生成 PDF 幻灯片的外观。

aspectratio

幻灯片纵横比（43 表示 4:3 [默认]，169 表示 16:9，1610 表示 16:10，149 表示 14:9，141 表示 1.41:1，54 表示 5:4，32 表示 3:2）

beameroption

使用 \setbeameroption{} 添加额外的 beamer 选项

institute

作者单位：多作者时可为列表

logo

幻灯片徽标图像

navigation

控制导航符号（默认为 empty 表示无导航符号；其他有效值为 frame、vertical 和 horizontal）

section-titles

为新节启用“标题页”（默认为 true）

theme, colortheme, fonttheme, innertheme, outertheme

beamer 主题

themeoptions, colorthemeoptions, fontthemeoptions, innerthemeoptions, outerthemeoptions

LaTeX beamer 主题选项（列表）

titlegraphic

标题幻灯片图像：可以是一个列表

titlegraphicoptions

标题幻灯片图像选项

shorttitle, shortsubtitle, shortauthor, shortinstitute, shortdate

一些 beamer 主题使用标题、副标题、作者、机构、日期的短版本

PowerPoint 变量

这些变量控制幻灯片的视觉方面，而这些方面不易通过模板控制。

monofont

用于代码的字体。

LaTeX 变量

Pandoc 在使用 LaTeX 引擎 创建 PDF 时使用这些变量。

ConTeXt 变量

Pandoc 在使用 ConTeXt 创建 PDF 时使用这些变量。

fontsize

正文的字体大小（例如 10pt，12pt）

headertext, footertext

放置在运行页眉或页脚中的文本（参见 ConTeXt 页眉和页脚）；最多重复四次以进行不同位置的放置

indenting

控制段落缩进，例如 yes,small,next（参见 ConTeXt 缩进）；多个选项重复

interlinespace

调整行间距，例如 4ex（使用 setupinterlinespace）；多个选项重复

layout

页面边距和文本排列选项（参见 ConTeXt 布局）；多个选项重复

linkcolor, contrastcolor

页面外部和内部链接的颜色，例如 red, blue（参见 ConTeXt 颜色）

linkstyle

链接的字体样式，例如 normal、bold、slanted、boldslanted、type、cap、small

lof, lot

包含图表列表、表格列表

mainfont, sansfont, monofont, mathfont

字体系列：接受任何系统字体名称（参见 ConTeXt 字体切换）

mainfontfallback, sansfontfallback, monofontfallback

要尝试的字体列表，按顺序排列，如果主字体中未找到字形。使用 \definefallbackfamily 兼容的字体名称语法。不支持 Emoji 字体。

margin-left, margin-right, margin-top, margin-bottom

设置页边距，如果未使用 layout（否则 layout 会覆盖这些设置）

pagenumbering

页码样式和位置（使用 setuppagenumbering）；多个选项重复

papersize

纸张大小，例如 letter、A4、landscape（参见 ConTeXt 纸张设置）；多个选项重复

pdfa

在序言中添加生成指定类型 PDF/A 所需的设置，例如 1a:2005、2a。如果未指定类型（即，值设置为 True，例如通过 --metadata=pdfa 或 YAML 元数据块中的 pdfa: true），出于向后兼容性原因，将默认使用 1b:2005。不支持在未指定值的情况下使用 --variable=pdfa。要成功生成 PDF/A，需要 ICC 颜色配置文件可用，并且内容和所有包含的文件（如图像）必须符合标准。ICC 配置文件和输出意图可以使用变量 pdfaiccprofile 和 pdfaintent 指定。另请参阅 ConTeXt PDFA 以获取更多详细信息。

pdfaiccprofile

与 pdfa 结合使用时，指定 PDF 中使用的 ICC 配置文件，例如 default.cmyk。如果未指定，则默认使用 sRGB.icc。可以重复以包含多个配置文件。请注意，配置文件必须在系统上可用。可以从 ConTeXt ICC Profiles 获取它们。

pdfaintent

与 pdfa 结合使用时，指定颜色的输出意图，例如 ISO coated v2 300\letterpercent\space (ECI)。如果未指定，则默认使用 sRGB IEC61966-2.1。

toc

包含目录（也可以使用 --toc/--table-of-contents 设置）

urlstyle

无链接文本链接的字体样式，例如 normal、bold、slanted、boldslanted、type、cap、small

whitespace

段落之间的间距，例如 none、small（使用 setupwhitespace）

includesource

将所有源文档作为文件附件包含在 PDF 文件中

wkhtmltopdf 变量

Pandoc 在使用 wkhtmltopdf 创建 PDF 时使用这些变量。--css 选项也会影响输出。

footer-html, header-html

在页眉和页脚中添加信息

margin-left, margin-right, margin-top, margin-bottom

设置页边距

papersize

设置 PDF 纸张大小

man 页面变量

adjusting

将文本调整到左（l）、右（r）、居中（c）或两边（b）页边距

footer

man 页面中的页脚

header

man 页面中的页眉

section

man 页面中的节号

Texinfo 变量

version

软件版本（用于标题和标题页）

filename

要生成的信息文件的名称（默认为基于 texi 文件名的名称）

Typst 变量

template

要使用的 Typst 模板。

margin

一个字典，包含 Typst 文档中定义的字段：x、y、top、bottom、left、right。

papersize

纸张大小：a4, us-letter 等。

mainfont

用于主字体的系统字体名称。

fontsize

字体大小（例如，12pt）。

section-numbering

用于节编号的方案，例如 1.A.1。

page-numbering

用于页码编号的方案，例如 1 或 i，或空字符串以省略页码编号。

columns

正文的列数。

ms 变量

fontfamily

A (Avant Garde), B (Bookman), C (Helvetica), HN (Helvetica Narrow), P (Palatino), 或 T (Times New Roman)。此设置不影响源代码，源代码始终使用等宽 Courier 显示。这些内置字体在字符覆盖方面有限。可以使用 Peter Schaffter 提供的脚本 install-font.sh 安装额外字体，其详细文档可在 他的网站 上找到。

indent

段落缩进（例如 2m）

lineheight

行高（例如 12p）

pointsize

磅值（例如 10p）

自动设置的变量

Pandoc 会根据 选项 或文档内容自动设置这些变量；用户也可以修改它们。这些变量因输出格式而异，包括以下内容：

body

文档正文

date-meta

转换为 ISO 8601 YYYY-MM-DD 格式的 date 变量，包含在所有基于 HTML 的格式中（dzslides, epub, html, html4, html5, revealjs, s5, slideous, slidy）。date 可识别的格式有：mm/dd/yyyy, mm/dd/yy, yyyy-mm-dd (ISO 8601), dd MM yyyy (例如 02 Apr 2018 或 02 April 2018), MM dd, yyyy (例如 Apr. 02, 2018 或 April 02, 2018), yyyy[mm[dd]] (例如 20180402, 201804 或 2018)。

header-includes

由 -H/--include-in-header 指定的内容（可以有多个值）

include-before

由 -B/--include-before-body 指定的内容（可以有多个值）

include-after

由 -A/--include-after-body 指定的内容（可以有多个值）

meta-json

文档所有元数据的 JSON 表示。字段值会转换为所选的输出格式。

numbersections

如果指定了 -N/--number-sections，则为非空值

sourcefile, outputfile

源文件和目标文件名，如命令行所示。如果输入来自多个文件，sourcefile 也可以是列表；如果输入来自标准输入，则为空。您可以在模板中使用以下片段来区分它们：

$if(sourcefile)$
$for(sourcefile)$
$sourcefile$
$endfor$
$else$
(stdin)
$endif$

同样，如果输出到终端，outputfile 可以是 -。

如果需要绝对路径，请使用例如 $curdir$/$sourcefile$。

pdf-engine

如果使用 --pdf-engine 提供了 PDF 引擎名称，或者如果请求 PDF 输出，则为该格式的默认引擎。

curdir

运行 pandoc 的工作目录。

pandoc-version

pandoc 版本。

toc

如果指定了 --toc/--table-of-contents，则为非空值

toc-title

目录标题（仅适用于 EPUB、HTML、revealjs、opendocument、odt、docx、pptx、beamer、LaTeX）。请注意，在 docx 和 pptx 中，自定义的 toc-title 将从元数据中获取，但不能设置为变量。

扩展：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 选项生成的目录提供链接目标。它们还方便了从文档的一个部分链接到另一个部分。例如，指向此部分的链接可能如下所示：

See the section on
[heading identifiers](#heading-identifiers-in-html-latex-and-context).

然而，请注意，这种提供章节链接的方法仅适用于 HTML、LaTeX 和 ConTeXt 格式。

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

扩展：ascii_identifiers ±

使 auto_identifiers 生成的标识符为纯 ASCII。带重音的拉丁字母会去除重音，非拉丁字母会被省略。

扩展：gfm_auto_identifiers ±

将 auto_identifiers 使用的算法更改为符合 GitHub 的方法。空格转换为连字符（-），大写字符转换为小写字符，除了 - 和 _ 之外的标点符号字符被移除。表情符号被替换为其名称。

扩展：literate_haskell ±

将文档视为 Haskell 文学编程源文件。

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

输入格式

markdown, rst, latex

输出格式

markdown, rst, latex, html

如果您在上述格式之一后附加 +lhs（或 +literate_haskell），pandoc 会将文档视为 Haskell 文学编程源文件。这意味着：

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

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

• 在 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 转换时，为所有 docx 样式添加 custom-styles 属性，无论 pandoc 是否理解这些样式的含义。因为属性不能直接添加到 pandoc AST 中的段落或文本中，段落样式将导致创建 Div 元素，字符样式将导致创建 Span 元素来保存属性。（表格样式将直接添加到 Table 元素中。）此扩展可与 docx 自定义样式一起使用。

输入格式

docx

扩展：amuse ±

在 muse 输入格式中，这将启用 Text::Amuse 对 Emacs Muse 标记的扩展。

扩展：raw_markdown ±

在 ipynb 输入格式中，这会导致 Markdown 单元格作为原始 Markdown 块（允许无损往返转换）而非被解析地包含进来。仅当您以 ipynb 或基于 Markdown 的输出格式为目标时才使用此功能。

扩展：citations (typst) ±

当 citations 扩展在 typst 中启用时（默认情况下启用），typst 引用将被解析为原生的 pandoc 引用，原生的 pandoc 引用将渲染为 typst 引用。

扩展：citations (org) ±

当 citations 扩展在 org 中启用时，org-cite 和 org-ref 样式的引用将被解析为原生的 pandoc 引用，并且 org-cite 引用将用于渲染原生的 pandoc 引用。

扩展：citations (docx) ±

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

扩展：fancy_lists (org) ±

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

扩展：element_citations ±

在 jats 输出格式中，这会导致引用项被替换为 <element-citation> 元素。这些元素不受 CSL 样式的影响，但项目的全部信息都包含在标签中。

扩展：ntb ±

在 context 输出格式中，这将启用 自然表格 (TABLE) 的使用，而非默认的 极限表格 (xtables)。自然表格允许更细粒度的全局定制，但与极限表格相比会带来性能损失。

扩展：tagging ±

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

扩展：escaped_line_breaks ±

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

Setext 样式标题

Setext 样式标题是一行文本，通过一行 = 符号（用于一级标题）或 - 符号（用于二级标题）“加下划线”

A level-one heading
===================

A level-two heading
-------------------

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

ATX 样式标题

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

## A level-two heading

### A level-three heading ###

与 Setext 样式标题一样，标题文本可以包含格式。

# A level-one heading with a [link](/url) and *emphasis*

扩展：blank_before_header ±

原始 Markdown 语法不要求标题前有空行。Pandoc 则要求有空行（当然，文档开头除外）。这样要求的原因是，# 符号很容易因意外（可能是换行）而出现在行首。例如，考虑以下情况

I like several of their flavors of ice cream:
#22, for example, and #5.

扩展：space_in_atx_header ±

许多 Markdown 实现不要求 ATX 标题开头的 # 符号与标题文本之间有空格，因此 #5 bolt 和 #hashtag 都被算作标题。启用此扩展后，pandoc 要求有空格。

标题标识符

另请参见上面的auto_identifiers 扩展。

扩展：header_attributes ±

标题可以在包含标题文本的行末使用此语法来分配属性

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

因此，例如，以下标题都将被分配标识符 foo

# My heading {#foo}

## My heading ##    {#foo}

My other heading   {#foo}
---------------

（此语法与 PHP Markdown Extra 兼容。）

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

带有 unnumbered 类的标题将不会被编号，即使指定了 --number-sections。在属性上下文中，单个连字符（-）等同于 .unnumbered，在非英语文档中更受欢迎。因此，

# My heading {-}

与...相同

# My heading {.unnumbered}

如果除了 unnumbered 之外还存在 unlisted 类，该标题将不会包含在目录中。（目前此功能仅针对某些格式实现：基于 LaTeX 和 HTML 的格式、PowerPoint 和 RTF。）

扩展：implicit_header_references ±

Pandoc 的行为就好像为每个标题都定义了引用链接一样。因此，要链接到一个标题

# Heading identifiers in HTML

您可以简单地写

[Heading identifiers in HTML]

或者

[Heading identifiers in HTML][]

或者

[the section on heading identifiers][heading identifiers in
HTML]

而不是显式地给出标识符

[Heading identifiers in HTML](#heading-identifiers-in-html)

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

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

显式链接引用定义始终优先于隐式标题引用。因此，在以下示例中，链接将指向 bar，而不是 #foo

# Foo

[foo]: bar

See [foo]

扩展：blank_before_blockquote ±

原始 Markdown 语法不要求块引用前有空行。Pandoc 则要求有空行（当然，文档开头除外）。这样要求的原因是，> 符号很容易因意外（可能是换行）而出现在行首。因此，除非使用 markdown_strict 格式，否则以下内容在 pandoc 中不会生成嵌套块引用

> This is a block quote.
>> Not nested, since `blank_before_blockquote` is enabled by default

缩进代码块

缩进四个空格（或一个制表符）的文本块被视为逐字文本：也就是说，特殊字符不会触发特殊格式，所有空格和换行符都将保留。例如，

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

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

注意：逐字文本中的空行不必以四个空格开头。

围栏式代码块

扩展：fenced_code_blocks ±

除了标准缩进代码块外，pandoc 还支持围栏式代码块。这些代码块以一排三个或更多波浪线（~）开头，并以一排波浪线结尾，且结尾的波浪线长度必须至少与开头的波浪线一样长。这些行之间的所有内容都将被视为代码。无需缩进

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

与普通代码块一样，围栏式代码块必须与周围文本用空行分隔。

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

~~~~~~~~~~~~~~~~
~~~~~~~~~~
code including tildes
~~~~~~~~~~
~~~~~~~~~~~~~~~~

扩展：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 格式化。这对于诗歌和地址很有用

| The limerick packs laughs anatomical
| In space that is quite economical.
|    But the good ones I've seen
|    So seldom are clean
| And the clean ones so seldom are comical

| 200 Main St.
| Berkeley, CA 94718

如果需要，行可以强制换行，但续行必须以一个空格开头。

| The Right Honorable Most Venerable and Righteous Samuel L.
  Constable, Jr.
| 200 Main St.
| Berkeley, CA 94718

内容中允许使用行内格式（例如强调），但不能跨行。不识别块级格式（例如块引用或列表）。

此语法借鉴自 reStructuredText。

无序列表

无序列表是项目符号列表项的列表。项目符号列表项以项目符号（*、+ 或 -）开头。这是一个简单示例

* one
* two
* three

这将生成一个“紧凑”列表。如果您想要一个“松散”列表，其中每个项目都格式化为一个段落，请在项目之间留出空格

* one

* two

* three

项目符号不必与左边距齐平；它们可以缩进一、二或三个空格。项目符号后面必须有空格。

如果后续行与第一行（在项目符号之后）齐平，列表项看起来最佳

* here is my first
  list item.
* and my second.

但 Markdown 也允许“懒惰”格式

* here is my first
list item.
* and my second.

列表项中的块内容

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

  * First paragraph.

    Continued.

  * Second paragraph. With a code block, which must be indented
    eight spaces:

        { code }

例外：如果列表标记后跟一个缩进代码块（该代码块必须在列表标记后空出 5 个空格开始），则后续段落必须在列表标记的最后一个字符之后两列开始

*     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-Flavored Markdown 的语法。

- [ ] an unchecked task list item
- [x] checked item

定义列表

扩展：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.

    Second paragraph of the definition.

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

Term 1
  ~ Definition 1

Term 2
  ~ Definition 2a
  ~ Definition 2b

请注意，定义列表中的项目之间需要有空格。（一个放宽此要求但禁止“懒惰”强制换行的变体，可以通过compact_definition_lists 扩展激活。）

编号示例列表

扩展：example_lists ±

特殊的列表标记 @ 可用于按顺序编号的示例。文档中第一个带有 @ 标记的列表项将被编号为“1”，下一个为“2”，依此类推。编号的示例不必出现在单个列表中；每个使用 @ 的新列表将从上一个列表停止的地方继续。因此，例如

(@)  My first example will be numbered (1).
(@)  My second example will be numbered (2).

Explanation of examples.

(@)  My third example will be numbered (3).

编号的示例可以在文档的其他地方被标记和引用

(@good)  This is a good example.

As (@good) illustrates, ...

标签可以是任何由字母数字字符、下划线或连字符组成的字符串。

示例列表中的续段落必须始终缩进四个空格，无论列表标记的长度如何。也就是说，示例列表始终表现为已设置 four_space_rule 扩展。这是因为示例标签通常较长，将内容缩进到标签后的第一个非空格字符会很尴尬。

您可以通过重复使用其标签来重复之前的编号示例

(@foo) Sample sentence.

Intervening text...

This theory can explain the case we saw earlier (repeated):

(@foo) Sample sentence.

然而，这只有在重复项单独位于一个列表中时才能可靠地工作，因为每个编号示例列表都将从其起始编号连续编号。

结束列表

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

-   item one
-   item two

    { my code block }

麻烦了！在这里，pandoc（像其他 Markdown 实现一样）会将 { my code block } 视为第二项的第二个段落，而不是一个代码块。

要在第二项后“截断”列表，您可以插入一些非缩进内容，例如 HTML 注释，这在任何格式中都不会产生可见输出

-   item one
-   item two

<!-- end of list -->

    { my code block }

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

1.  one
2.  two
3.  three

<!-- -->

1.  uno
2.  dos
3.  tres

扩展：table_captions ±

所有四种表格都可以选择提供标题（如下例所示）。标题是一个以字符串 Table:（或 table: 或仅 :）开头的段落，该字符串将被剥离。它可以出现在表格之前或之后。

扩展：simple_tables ±

简单表格如下所示

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

Table:  Demonstration of simple table syntax.

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

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

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

列标题行可以省略，但前提是使用虚线来结束表格。例如

-------     ------ ----------   -------
     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: Here's the caption. It, too, may span
multiple lines.

它们的工作方式与简单表格类似，但有以下不同之处

• 它们必须在表头文本之前以一行虚线开头（除非省略表头行）。
• 它们必须以一行虚线，然后一个空行结束。
• 行必须用空行分隔。

在多行表格中，表格解析器会关注列的宽度，并且写入器会尝试在输出中重现这些相对宽度。因此，如果您发现输出中的某一列太窄，请尝试在 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 ±

如果文件以标题块开头

% title
% author(s) (separated by semicolons)
% date

它将被解析为书目信息，而不是常规文本。（例如，它将用于独立 LaTeX 或 HTML 输出的标题。）该块可以只包含标题、日期和作者，或者这三个元素。如果您想包含作者但没有标题，或者有标题和日期但没有作者，您需要一个空行

%
% Author

% My title
%
% June 15, 2006

标题可以占据多行，但续行必须以开头空格开始，因此

% My title
  on multiple lines

如果文档有多个作者，作者可以放在单独的行上，带有前导空格，或者用分号分隔，或者两者兼有。因此，以下所有内容都是等效的

% Author One
  Author Two

% Author One; Author Two

% Author One;
  Author Two

日期必须在一行内。

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

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

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

% PANDOC(1)

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

% PANDOC(1) Pandoc User Manuals

页脚也将包含“Pandoc User Manuals”。

% PANDOC(1) Pandoc User Manuals | Version 4.0

页眉也将包含“Version 4.0”。

扩展：yaml_metadata_block ±

一个 YAML 元数据块是一个有效的 YAML 对象，顶部由一行三个连字符（---）分隔，底部由一行三个连字符（---）或三个点（...）分隔。初始行 --- 后不能有空行。YAML 元数据块可以出现在文档的任何位置，但如果它不在开头，则必须在其前面有一个空行。

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

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:  'This is the title: it contains a colon'
author:
- Author One
- Author Two
keywords: [nothing, nothingness]
abstract: |
  This is the abstract.

  It consists of two paragraphs.
...

| 后面的字面块必须相对于包含 | 的行进行缩进。否则，YAML 将无效，pandoc 也不会将其解释为元数据。有关 YAML 复杂规则的概述，请参阅 维基百科上的 YAML 语法条目。

模板变量将从元数据中自动设置。因此，例如，在编写 HTML 时，变量 abstract 将设置为 abstract 字段中 Markdown 的 HTML 等效内容

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

变量可以包含任意 YAML 结构，但模板必须与此结构匹配。默认模板中的 author 变量需要一个简单的列表或字符串，但可以更改以支持更复杂的结构。例如，以下组合将在给定作者的情况下为其添加隶属关系

---
title: The document title
author:
- name: Author One
  affiliation: University of Somewhere
- name: Author Two
  affiliation: University of Nowhere
...

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

$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 通过行末两个尾随空格来指示强制换行的“不可见”方式的一个很好的替代方案。

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

强调

要强调某些文本，请用 * 或 _ 将其包围，像这样

This text is _emphasized with underscores_, and this
is *emphasized with asterisks*.

双重 * 或 _ 会产生强强调

This is **strong emphasis** and __with underscores__.

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

This is * not emphasized *, and \*neither is this\*.

扩展：intraword_underscores ±

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

feas*ible*, not feas*able*.

删除线

扩展：strikeout ±

要用横线划掉一段文本，请用 ~~ 将其包围。因此，例如，

This ~~is deleted text.~~

上标和下标

扩展：superscript, subscript ±

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

H~2~O is a liquid.  2^10^ is 1024.

^...^ 或 ~...~ 之间的文本不能包含空格或换行符。如果上标或下标文本包含空格，这些空格必须用反斜杠转义。（这是为了防止通过普通使用 ~ 和 ^ 导致意外上标和下标，以及与脚注的不良交互。）因此，如果您想要字母 P 带“a cat”的下标，请使用 P~a\ cat~，而不是 P~a cat~。

逐字

要使一小段文本逐字显示，请将其放在反引号内

What is the difference between `>>=` and `>>`?

如果逐字文本包含反引号，请使用双反引号

Here is a literal backtick `` ` ``.

（起始反引号后的空格和结束反引号前的空格将被忽略。）

一般规则是，逐字跨度以一串连续的反引号（可选地后跟一个空格）开始，并以相同数量的反引号（可选地前跟一个空格）结束。

请注意，反斜杠转义（以及其他 Markdown 构造）在逐字上下文中不起作用

This is a backslash followed by an asterisk: `\*`.

扩展：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 mode, ConTeXt, ZimWiki

它将逐字显示，并由 $...$（用于行内数学公式）或 $$...$$（用于显示数学公式）包围。

XWiki

它将逐字显示，并由 {{formula}}..{{/formula}} 包围。

reStructuredText

它将使用解释文本角色 :math:进行渲染。

AsciiDoc

对于 AsciiDoc 输出，数学公式将逐字显示，并由 latexmath:[...] 包围。对于 asciidoc_legacy，方括号内的内容还将包括行内或显示数学分隔符。

Texinfo

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

roff man, Jira markup

它将逐字渲染，不带 $ 符号。

MediaWiki, DokuWiki

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

Textile

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

RTF, OpenDocument

如果可能，它将使用 Unicode 字符渲染，否则将逐字显示。

ODT

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

DocBook

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

Docx and PowerPoint

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

FictionBook2

如果使用 --webtex 选项，公式将使用 CodeCogs 或其他兼容的 Web 服务渲染为图像，下载并嵌入到电子书中。否则，它们将逐字显示。

HTML, Slidy, DZSlides, S5, EPUB

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

扩展：raw_html ±

Markdown 允许您在文档中的任何位置插入原始 HTML（或 DocBook）（除了逐字上下文，在其中 <、> 和 & 会被字面解释）。（从技术上讲，这不是一个扩展，因为标准 Markdown 允许它，但为了可以根据需要禁用，它已被设置为一个扩展。）

原始 HTML 在 HTML、S5、Slidy、Slideous、DZSlides、EPUB、Markdown、CommonMark、Emacs Org mode 和 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 块元素混合使用变得更容易。例如，可以用 <div> 标签包围 Markdown 文本块，而不会阻止它被解释为 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 引用

This result was proved in \cite{jones.1967}.

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

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

begin 和 end 标签之间的内容将被解释为原始 LaTeX，而不是 Markdown。

要以更明确和灵活的方式在 Markdown 文档中包含原始 TeX，请参见raw_attribute 扩展。

行内 LaTeX 在 Markdown、LaTeX、Emacs Org mode 和 ConTeXt 之外的输出格式中会被忽略。

通用原始属性

扩展：raw_attribute ±

行内 span 和带有特殊属性的围栏式代码块将被解析为指定格式的原始内容。例如，以下内容会生成一个原始的 roff ms 块：

```{=ms}
.MYMACRO
blah blah
```

以下内容会生成一个原始的 html 行内元素：

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

这对于将原始 XML 插入 docx 文档非常有用，例如插入一个分页符：

```{=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_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 内容传递。Markdown 源（或其他允许 raw_tex 的格式）中的宏定义无论是否启用 latex_macros 都会被传递。

自动链接

如果您将 URL 或电子邮件地址用尖括号括起来，它将成为一个链接：

<https://google.com>
<[email protected]>

行内链接

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

This is an [inline link](/url), and here's [one with
a title](https://fsf.org "click here for a good time!").

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

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

[Write me!](mailto:[email protected])

引用链接

一个显式引用链接由两部分组成：链接本身和链接定义，链接定义可以出现在文档的其他地方（在链接之前或之后）。

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

以下是一些示例：

[my label 1]: /foo/bar.html  "My title, optional"
[my label 2]: /foo
[my label 3]: https://fsf.org (The Free Software Foundation)
[my label 4]: /bar#special  'A title in single quotes'

URL 可以选择用尖括号括起来：

[my label 5]: <http://foo.bar.baz>

标题可以放在下一行：

[my label 3]: https://fsf.org
  "The Free Software Foundation"

请注意，链接标签不区分大小写。因此，以下内容将生效：

Here is [my link][FOO]

[Foo]: /bar/baz

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

See [my website][].

[my website]: http://foo.bar.baz

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

> My block [quote].
>
> [quote]: /foo

扩展：shortcut_reference_links ±

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

See [my website].

[my website]: http://foo.bar.baz

内部链接

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

See the [Introduction](#introduction).

或者

See the [Introduction].

[Introduction]: #introduction

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

扩展：implicit_figures ±

一个带有非空替代文本的图像，如果单独出现在一个段落中，将作为带标题的图渲染。图像的替代文本将用作标题。

![This is the caption](/url/of/image.png)

如何渲染取决于输出格式。某些输出格式（例如 RTF）尚不支持图。在这些格式中，您只会得到一个单独在段落中的图像，没有标题。

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

![This image won't be a figure](/url/of/image.png)\

请注意，在 reveal.js 幻灯片中，如果段落中单独存在的图像带有 r-stretch 类，它将填满屏幕，并且将省略标题和图标签。

扩展：link_attributes ±

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

An inline ![image](foo.jpg){#id .class width=30 height=20px}
and a reference ![image][ref] with attributes.

[ref]: foo.jpg "optional title" {#id .class key=val key2="val 2"}

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

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

图像上的 width 和 height 属性将进行特殊处理。当不带单位使用时，单位假定为像素。但是，可以使用以下任何单位标识符：px、cm、mm、in、inch 和 %。数字和单位之间不能有空格。例如：

![](file.jpg){ width=50% }

• 尺寸可能会被转换为与输出格式兼容的形式（例如，当将 HTML 转换为 LaTeX 时，以像素为单位的尺寸将被转换为英寸）。像素和物理测量之间的转换受 --dpi 选项的影响（默认情况下，假定为 96 dpi，除非图像本身包含 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 元数据。

扩展：fenced_divs ±

允许对原生 Div 块使用特殊的围栏式语法。一个 Div 以一个包含至少三个连续冒号加上一些属性的围栏开始。属性后面可以选择性地跟一个连续冒号的字符串。

注意：commonmark 解析器不允许属性后面有冒号。

属性语法与围栏式代码块中的属性语法完全相同（请参阅扩展：fenced_code_attributes）。与围栏式代码块一样，可以使用花括号中的属性或单个不带花括号的单词，该单词将被视为类名。Div 以另一行结束，该行包含一个至少三个连续冒号的字符串。围栏式 Div 应与前后块之间用空行分隔。

示例：

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

And another.
:::::

围栏式 Div 可以嵌套。开围栏的特点是它们必须有属性：

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

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

没有属性的围栏总是闭围栏。与围栏式代码块不同，闭围栏中的冒号数量不需要与开围栏中的数量匹配。但是，使用不同长度的围栏来区分嵌套 div 与其父 div，有助于提高视觉清晰度。

扩展：bracketed_spans ±

一个用方括号括起来的行内序列，就像开始一个链接一样，如果后面紧跟着属性，将被视为一个带有属性的 Span：

[This is *some text*]{.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 ±

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

Here is an inline note.^[Inline notes are easier to write, since
you don't have to pick an identifier and move down to type the
note.]

行内脚注和常规脚注可以自由混合使用。

扩展：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 says blah [-@smith04].

您还可以通过省略方括号来编写文本内作者引用：

@smith04 says blah.

@smith04 [p. 33] says blah.

这将导致作者姓名被渲染，后跟书目详细信息。当您想将引用作为句子的主语时，请使用此形式。

当您使用注释样式时，通常最好让 citeproc 从引用创建脚注，而不是手动编写显式注释。如果您确实编写了包含引用的显式注释，请注意，正常引用将放在括号中，而文本内引用则不会。因此，在使用注释样式时，有时最好在注释内部使用文本内样式。

扩展：rebase_relative_paths ±

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

此扩展的使用最好通过示例来理解。假设您为书的每个章节都有一个子目录，chap1、chap2、chap3。每个子目录都包含一个 text.md 文件和章节中使用的许多图像。您希望 chap1/text.md 中的 ![image](spider.jpg) 指向 chap1/spider.jpg，而 chap2/text.md 中的 ![image](spider.jpg) 指向 chap2/spider.jpg。为此，请使用：

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

如果没有此扩展，您将不得不在 chap1/text.md 中使用 ![image](chap1/spider.jpg)，并在 chap2/text.md 中使用 ![image](chap2/spider.jpg)。带有相对路径的链接将以与图像相同的方式重写。

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

请注意，引用链接和图像中的相对路径将相对于包含链接引用定义的文件重写，而不是相对于包含引用链接或图像本身的文件，如果它们不同。

扩展：mark ±

要突出显示文本部分，请以 == 开始和结束。例如：

This ==is deleted text.==

扩展：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 版本的智能破折号解析行为：数字前的 - 是半破折号（en-dash），-- 是全破折号（em-dash）。此选项仅在启用 smart 时有效。对于 textile 输入，它会自动选择。

扩展：angle_brackets_escapable ±

允许 < 和 > 使用反斜杠转义，就像在 GitHub flavored 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:   My title
Author:  John Doe
Date:    September 1, 2008
Comment: This is a sample mmd title block, with
         a field spanning multiple lines.

详情请参阅 MultiMarkdown 文档。如果 pandoc_title_block 或 yaml_metadata_block 启用，它将优先于 mmd_title_block。

扩展：abbreviations ±

解析 PHP Markdown Extra 的缩写键，例如：

*[HTML]: Hypertext Markup Language

请注意，Pandoc 文档模型不支持缩写，因此如果启用此扩展，缩写键将被简单跳过（而不是被解析为段落）。

扩展：alerts ±

支持 GitHub 风格的 Markdown 警报，例如：

> [!TIP]
> Helpful advice for doing things better or more easily.

注意：此扩展目前仅适用于 commonmark：commonmark、gfm、commonmark_x。

扩展：autolink_bare_uris ±

使所有绝对 URI 都成为链接，即使它们未被尖括号 <...> 括起来。

扩展：mmd_link_attributes ±

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

This is a reference ![image][ref] with MultiMarkdown attributes.

[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 及更早版本的定义列表语法。此语法与上文定义列表中描述的语法在几个方面有所不同：

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

扩展：gutenberg ±

对 plain 输出使用 古腾堡计划约定：全大写表示强强调，用下划线括起来表示常规强调，标题周围添加额外的空白。

扩展：sourcepos ±

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

扩展：short_subsuperscripts ±

解析 MultiMarkdown 风格的下标和上标，它们分别以“~”或“^”字符开头，并包含后面的字母数字序列。例如：

x^2 = 4

或者

Oxygen is O~2.

扩展：wikilinks_title_after_pipe ±

Pandoc 支持多种 Markdown wiki 链接语法，无论标题是在竖线之前还是之后。

使用 --from=markdown+wikilinks_title_after_pipe 会得到：

[[URL|title]]

而使用 --from=markdown+wikilinks_title_before_pipe 会得到：

[[title|URL]]

标题中的大写

如果您正在使用 bibtex 或 biblatex 书目，请遵守以下规则：

• 英文标题应采用标题大小写。非英文标题应采用句子大小写，并且 biblatex 中的 langid 字段应设置为相关语言。（以下值被视为英文：american, british, canadian, english, australian, newzealand, USenglish, 或 UKenglish。）

• 按照 bibtex/biblatex 的标准，专有名词应受花括号保护，以免在要求句子大小写的样式中被小写。例如：

  title = {My Dinner with {Andre}}

• 此外，应保护应保持小写（或驼峰式）的单词：

  title = {Spin Wave Dispersion on the {nm} Scale}

  虽然在 bibtex/biblatex 中这不是必需的，但在 citeproc 中是必需的，citeproc 内部以句子大小写存储标题，并在需要时转换为标题大小写。在这里，我们保护“nm”，使其在此阶段不会转换为“Nm”。

如果您使用 CSL 书目（JSON 或 YAML），请遵守以下规则：

• 所有标题都应采用句子大小写。

• 对于非英文标题，请使用 language 字段以防止其在需要时转换为标题大小写。（仅当 language 以 en 开头或为空时才发生转换。）

• 使用此语法保护不应转换为标题大小写的单词：

  Spin wave dispersion on the <span class="nocase">nm</span> scale

会议论文，已发表 vs. 未发表

对于正式发表的会议论文，请使用 biblatex 条目类型 inproceedings（将映射到 CSL paper-conference）。

对于未发表的手稿，请使用不带 eventtitle 字段的 biblatex 条目类型 unpublished（此条目类型将映射到 CSL manuscript）。

对于演讲、未发表的会议论文或海报展示，请使用带有 eventtitle 字段的 biblatex 条目类型 unpublished（此条目类型将映射到 CSL speech）。使用 biblatex type 字段指示类型，例如“Paper”或“Poster”。venue 和 eventdate 也可能有用，尽管大多数 CSL 样式不会渲染 eventdate。请注意，venue 是指活动地点，与描述出版商地点的 location 不同；未发表的会议论文不要使用后者。

PowerPoint 布局选择

创建幻灯片时，pptx 写入器根据幻灯片内容从多个预定义布局中选择：

标题幻灯片

此布局用于初始幻灯片，如果存在 date、author 和 title 元数据字段，则从中生成并填充。

节标题

此布局用于 Pandoc 所称的“标题幻灯片”，即以层次结构中高于幻灯片级别的标题开头的幻灯片。

两栏内容

此布局用于双列幻灯片，即包含一个类为 columns 的 div，且该 div 中包含至少两个类为 column 且带有 width 属性的 div 的幻灯片。

比较

此布局用于任何至少有一列包含文本后跟非文本（例如图像或表格）的双列幻灯片，替代“Two Content”布局。

带标题内容

此布局用于任何非双列幻灯片，其中包含文本后跟非文本（例如图像或表格）。

空白

此布局用于任何只包含空白内容的幻灯片，例如只包含演讲者备注的幻灯片，或只包含不间断空格的幻灯片。

标题和内容

此布局用于所有不符合其他布局标准的幻灯片。

这些布局选自 Pandoc 附带的默认 pptx 引用文档，除非使用 --reference-doc 指定了替代引用文档。

beamer 中的附加列属性

类为 columns 和 column 的 div 容器可以选择具有 align 属性。类为 columns 可以选择具有 totalwidth 属性或 onlytextwidth 类。

:::::::::::::: {.columns align=center totalwidth=8em}
::: {.column width="40%"}
contents...
:::
::: {.column width="60%" align=bottom}
contents...
:::
::::::::::::::

columns 和 column 上的 align 属性可与 top、top-baseline、center 和 bottom 值一起使用，以垂直对齐列。在 columns 中，它默认为 top。

totalwidth 属性将列的宽度限制为给定值。

:::::::::::::: {.columns align=top .onlytextwidth}
::: {.column width="40%" align=center}
contents...
:::
::: {.column width="60%"}
contents...
:::
::::::::::::::

onlytextwidth 类将 totalwidth 设置为 \textwidth。

有关更多详细信息，请参阅 Beamer 用户指南的第 12.7 节。

所有幻灯片上（beamer、reveal.js、pptx）

对于 beamer 和 reveal.js，background-image 配置选项可以在 YAML 元数据块中或作为命令行变量使用，以便在每张幻灯片上获得相同的图像。

请注意，对于 reveal.js，background-image 将用作 parallaxBackgroundImage（见下文）。

对于 pptx，您可以使用一个 --reference-doc，其中已在相关布局上设置了背景图像。

在单个幻灯片上（reveal.js、pptx）

要为特定的 reveal.js 或 pptx 幻灯片设置图像，请将 {background-image="/path/to/image"} 添加到幻灯片上的第一个幻灯片级别标题（甚至可以是空的）。

由于 HTML 写入器会透传未知属性，其他 reveal.js 背景设置也适用于单个幻灯片，包括 background-size、background-repeat、background-color、transition 和 transition-speed。（data- 前缀将自动添加。）

注意：为了与 reveal.js 保持一致，pptx 也支持 data-background-image – 如果找不到 background-image，将检查 data-background-image。

在标题幻灯片上（reveal.js、pptx）

要为 reveal.js 自动生成的标题幻灯片添加背景图像，请在 YAML 元数据块中使用 title-slide-attributes 变量。它必须包含属性名称和值的映射。（请注意，此处需要 data- 前缀，因为它不会自动添加。）

对于 pptx，请传递一个设置了“标题幻灯片”布局背景图像的 --reference-doc。

示例 (reveal.js)

---
title: My Slide Show
parallaxBackgroundImage: /path/to/my/background_image.png
title-slide-attributes:
    data-background-image: /path/to/title_image.png
    data-background-size: contain
---

## Slide One

Slide 1 has background_image.png as its background.

## {background-image="/path/to/special_image.jpg"}

Slide 2 has a special image for its background, even though the heading has no content.