• Pandoc’s markdown 语法
    • 前言
    • Pandoc’s markdown
    • 哲学
    • 段落
    • 标题
      • Setext 风格标题
      • Atx 风格标题
    • HTML, LaTeX 与ConTeXt 的标题识别符
    • 区块引言
    • 字面(代码)区块
      • 缩进代码区块
      • 围栏代码区块
    • 行区块
    • 清单
      • 无序清单
      • 四个空白规则
      • 有序清单
      • 定义清单
      • 编号范例清单
      • 紧凑与宽松清单
      • 结束一个清单
    • 分隔线
    • 表格
      • 简单表格
      • 多行表格
      • 格框表格
      • 管线表格
    • 文件标题区块
    • 反斜线跳脱字元
    • 智慧型标点符号
    • 行内格式
      • 强调
      • 删除线
      • 上标与下标
      • 字面文字
    • 数学
  • produces myfile.html and images in myfile-images
    • Raw HTML
    • Raw TeX
    • LaTeX 巨集
    • 连结
      • 自动连结
      • 行内连结
      • 参考连结
      • 内部连结
    • 图片
      • 附上说明的图片
    • 脚注
    • 引用

    Pandoc’s markdown 语法

    前言

    这份文件是Pandoc版本Markdown语法的中文翻译。Pandoc本身是由John MacFarlane所开发的文件转换工具,可以在HTML, Markdown, PDF, TeX…等等格式之间进行转换。有许多喜欢纯文字编辑的人,利用Pandoc来进行论文的撰写或投影片制作。但除了转换的功能外,Pandoc所定义的Markdown扩充语法也是这套工具的一大亮点,在Pandoc的官方使用说明文件中,光是其针对Markdown格式的扩充就占了整整一半左右的篇幅。

    本文件翻译自Pandoc - Pandoc User’s Guide中的“Pandoc’s markdown”一节。你可以看看这份文件的原始档、产生文件所使用的HTML范本,以及转换时的命令参数。

    以下翻译开始。

    Pandoc’s markdown

    与John Gruber的原始markdown相比,Pandoc版本的markdown在语法上有额外的扩充与些许的修正。这份文件解释了这些语法,并指出其与原始markdown的差异所在。除非特别提到,不然这些差异均可藉由使用markdown_strict而非markdown的格式来关闭。单独一项扩充也可透过+EXTENSION-EXTENSION的方式来开启或关闭。例如,markdown_strict+footnotes表示加上脚注扩充的原始markdown,而markdown-footnotes-pipe_tables则是拿掉了脚注与管线表格扩充的pandoc markdown。

    哲学

    Markdown 是针对易于书写与阅读的目标而设计的,特别是在易于阅读这点上尤为重要:

    一份Markdown格式的文件应该要能以纯文字形式直接发表,并且一眼看过去不存在任何标记用的标签或格式指令。John Gruber

    这项原则同样也是pandoc 在制订表格、脚注以及其他扩充的语法时,所依循的规范。

    然而,pandoc 的目标与原始markdown 的最初目标有着方向性的不同。在markdown 原本的设计中,HTML 是其主要输出对象;然而pandoc 则是针对多种输出格式而设计。因此,虽然pandoc 同样也允许直接嵌入HTML 标签,但并不鼓励这样的作法,取而代之的是pandoc 提供了许多非HTML 的方式,来让使用者输入像是定义清单、表格、数学公式以及脚注等诸如此类的重要文件元素。

    段落

    一个段落指的是一行以上的文字,跟在一行以上的空白行之后。换行字元会被当作是空白处理,因此你可以依自己喜好排列段落文字。如果你需要强制换行,在行尾放上两个以上的空白字元即可。

    Extension: escaped_line_breaks

    一个反斜线后跟着一个换行字元,同样也有强制换行的效果。

    标题

    有两种不同形式的标题语法,Setext 以及atx。

    Setext 风格标题

    Setext风格的标题是由一行文字底下接着一行=符号(用于一阶标题)或-符号(用于二阶标题)所构成:

    1. A level-one header
    2. ==================
    3. A level-two header
    4. ------------------

    标题的文字可以包含行内格式,例如强调(见下方行内格式一节)。

    Atx 风格标题

    Atx风格的标题是由一到六个#符号以及一行文字所组成,你可以在文字后面加上任意数量的#符号。由行首起算的#符号数量决定了标题的阶层:

    1. ## A level-two header
    2. ### A level-three header ###

    如同setext 风格标题,这里的标题文字同样可包含行内格式:

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

    Extension: blank_before_header

    原始markdown语法在标题之前并不需要预留空白行。Pandoc则需要(除非标题位于文件最开始的地方)。这是因为以#符号开头的情况在一般文字段落中相当常见,这会导致非预期的标题。例如下面的例子:

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

    HTML, LaTeX 与ConTeXt 的标题识别符

    Extension: header_attributes

    在标题文字所在行的行尾,可以使用以下语法为标题加上属性:

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

    虽然这个语法也包含加入类别(class)以及键/值形式的属性(attribute),但目前只有识别符(identifier/ID)在输出时有实际作用(且只在部分格式的输出,包括:HTML, LaTeX, ConTeXt, Textile, AsciiDoc)。举例来说,下面是将标题加上foo识别符的几种方法:

    1. # My header {#foo}
    2. ## My header ## {#foo}
    3. My other header {#foo}
    4. ---------------

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

    具有unnumbered类别的标题将不会被编号,即使--number-sections的选项是开启的。单一连字符号( - )等同于.unnumbered,且更适用于非英文文件中。因此,

    1. # My header {-}

    与下面这行是等价的

    1. # My header {.unnumbered}

    Extension: auto_identifiers

    没有明确指定ID(识别符)的标题将会依据其标题文字,自动指派一个独一无二的ID。由标题文字推导ID 的规则如下:

    • 移除所有格式,连结等。
    • 移除所有标点符号,除了底线、连字符号与句号。
    • 以连字符号取代所有空白与换行字元。
    • 将所有英文字母转为小写。
    • 移除第一个字元前的所有内容(ID 不能以数字或标点符号开头)。
    • 如果剩下为空字串,则使用section作为ID。

    以下是一些范例,

    HeaderIdentifier

    Header identifiers in HTML
    header-identifiers-in-html

    Dogs ?–in my house?
    dogs--in-my-house

    [HTML], [S5], or [RTF]?
    html-s5-or-rtf

    1. Applications
      applications

    33
    section

    在大多数情况下,这些规则应该让人能够直接从标题文字推导出ID。唯一的例外是当有多个标题具有同样文字的情况;在这情况下,第一个标题的ID仍旧是透过以上规则推导而得;第二个则是在同样ID后加上-1;第三个加上-2;以此类推。

    在开启--toc|--table-of-contents的选项时,这些ID是用来产生目录(Table of Contents)所需的页面连结。此外,这些ID也提供了一个简便的方式来输入跳到指定章节的连结。一个以ID产生的连结,其使用的语法看起来就像下面的例子:

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

    然而要注意的一点是,只有在以HTML、LaTeX 与ConTeXt 格式输出时,才能以这种方式产生对应的章节连结。

    如果指定了--section-divs选项,则每一个小节都会以div标签包住(或是section标签,如果有指定--html5选项的话),并且ID会被附加在用来包住小节的<div >(或是<section>)标签,而非附加在标题上。这使得整个小节都可以透过javascript来操作,或是采用不同的CSS设定。

    Extension: implicit_header_references

    Pandoc 假设每个标题都定义了其参考连结,因此,相较于以下的连结语法

    1. [header identifiers](#header-identifiers-in-html)

    你也可以单纯只写

    1. [header identifiers]

    1. [header identifiers][]

    1. [the section on header identifiers][header identifiers]

    如果有多个标题具有同样文字,对应的参考只会连结到第一个符合的标题,这时若要连结到其他符合的标题,就必须以先前提到的方式,明确指定连结到该标题的ID 。

    与其他一般参考连结不同的是,这些参考连结是大小写有别的。

    注意:如果你有明确定义了任何一个标题的标示符,那么选项implicit_header_references就没有作用。

    区块引言

    Markdown使用email的习惯来建立引言区块。一个引言区块可以由一或多个段落或其他的区块元素(如清单或标题)组成,并且其行首均是由一个>符号加上一个空白作为开头。(>符号不一定要位在该行最左边,但也不能缩进超过三个空白)。

    1. > This is a block quote. This
    2. > paragraph has two lines.
    3. >
    4. > 1. This is a list inside a block quote.
    5. > 2. Second item.

    有一个「偷懒」的形式:你只需要在引言区块的第一行行首输入>即可,后面的行首可以省略符号:

    1. > This is a block quote. This
    2. paragraph has two lines.
    3. > 1. This is a list inside a block quote.
    4. 2. Second item.

    由于区块引言可包含其他区块元素,而区块引言本身也是区块元素,所以,引言是可以嵌套入其他引言的。

    1. > This is a block quote.
    2. >
    3. > > A block quote within a block quote.

    Extension: blank_before_blockquote

    原始markdown语法在区块引言之前并不需要预留空白行。Pandoc则需要(除非区块引言位于文件最开始的地方)。这是因为以>符号开头的情况在一般文字段落中相当常见(也许由于断行所致),这会导致非预期的格式。因此,除非是指定为markdown_strict格式,不然以下的语法在pandoc中将不会产生出嵌套区块引言:

    1. > This is a block quote.
    2. >> Nested.

    字面(代码)区块

    缩进代码区块

    一段以四个空白(或一个tab)缩进的文字区块会被视为字面区块(Verbatim Block):换句话说,特殊字元并不会转换为任何格式,单纯只以字面形式呈现,而所有的空白与换行也都会被保留。例如,

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

    位于行首的缩排(四个空白或一个tab)并不会被视为字面区块的一部分,因此在输出时会被移除掉。

    注意:在字面文字之间的空白行并不需要也以四个空白字元做开头。

    围栏代码区块

    Extension: fenced_code_blocks

    除了 ​​标准的缩进代码区块外,Pandoc也支援了围栏 ( fenced )代码区块的语法。这区块需以包含三个以上波浪线( ~ )或反引号( ``` )的一行作为开始,并以同样符号且至少同样长度的一行作为结束。所有介于开始与结束之间的文字行都会视为代码。不需要额外的缩进:

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

    如同一般的代码区块,围栏代码区块与其前后的文字之间必须以空白行作间隔。

    如果代码本身也包含了一整行的波浪线或反引号,那么只要在区块首尾处使用更长的波浪线或反引号即可:

    1. ~~~~~~~~~~~~~~~~
    2. ~~~~~~~~~~
    3. code including tildes
    4. ~~~~~~~~~~
    5. ~~~~~~~~~~~~~~~~

    你也可以选择性地使用以下语法附加属性到代码区块上:

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

    这里的mycode为ID,haskellnumberLines是类别,而startsFrom则是值为100的属性。有些输出格式可以利用这些资讯来作语法高亮。目前有使用到这些资讯的输出格式仅有HTML与LaTeX。如果指定的输出格式及语言类别有支援语法高亮,那么上面那段代码区块将会以高亮并带有行号的方式呈现。(要查询支援的程式语言清单,可在命令列输入pandoc --version。)反之若无支援,则上面那段代码区块则会以下面的形式呈现:

    1. <pre id="mycode" class="haskell numberLines" startFrom="100">
    2. <code>
    3. ...
    4. </code>
    5. </pre>

    下面这个是针对代码区块只有指定程式语言属性的简便形式:

    1. ```haskell
    2. qsort [] = []
    3. ```

    这与下面这行的效果是相同的:

    1. ``` {.haskell}
    2. qsort [] = []
    3. ```

    要取消所有语法高亮,使用--no-highlight选项。要设定语法高亮的配色,则使用--highlight-style

    行区块

    Extension: line_blocks

    行区块是一连串以竖线( | )加上一个空格所构成的连续行。行与行间的区隔在输出时将会以原样保留,行首的空白字元数目也一样会被保留;反之,这些行将会以markdown的格式处理。这个语法在输入诗句或地址时很有帮助。

    1. | The limerick packs laughs anatomical
    2. | In space that is quite economical.
    3. | But the good ones I've seen
    4. | So seldom are clean
    5. | And the clean ones so seldom are comical
    6. | 200 Main St.
    7. | Berkeley, CA 94718

    如果有需要的话,书写时也可以将完整一行拆成多行,但后续行必须以空白作为开始。下面范例的前两行在输出时会被视为一整行:

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

    这是从reStructuredText借来的语法。

    清单

    无序清单

    无序清单是以项目符号作列举的清单。每条项目都以项目符号( * , +- )作开头。下面是个简单的例子:

    1. * one
    2. * two
    3. * three

    这会产生一个「紧凑」清单。如果你想要一个「宽松」清单,也就是说以段落格式处理每个项目内的文字内容,那么只要在每个项目间加上空白行即可:

    1. * one
    2. * two
    3. * three

    项目符号不能直接从行首最左边处输入,而必须以一至三个空白字元作缩进。项目符号后必须跟着一个空白字元。

    清单项目中的接续行,若与该项目的第一行文字对齐(在项目符号之后),看上去会较为美观:

    1. * here is my first
    2. list item.
    3. * and my second.

    但markdown 也允许以下「偷懒」的格式:

    1. * here is my first
    2. list item.
    3. * and my second.

    四个空白规则

    一个清单项目可以包含多个段落以及其他区块等级的内容。然而,后续的段落必须接在空白行之后,并且以四个空白或一个tab 作缩进。因此,如果项目里第一个段落与后面段落对齐的话(也就是项目符号前置入两个空白),看上去会比较整齐美观:

    1. * First paragraph.
    2. Continued.
    3. * Second paragraph. With a code block, which must be indented
    4. eight spaces:
    5. { code }

    清单项目也可以包含其他清单。在这情况下前置的空白行是可有可无的。嵌套清单必须以四个空白或一个tab 作缩进:

    1. * fruits
    2. + apples
    3. - macintosh
    4. - red delicious
    5. + pears
    6. + peaches
    7. * vegetables
    8. + brocolli
    9. + chard

    上一节提到,markdown 允许你以「偷懒」的方式书写,项目的接续行可以不和第一行对齐。不过,如果一个清单项目中包含了多个段落或是其他区块元素,那么每个元素的第一行都必须缩进对齐。

    1. + A lazy, lazy, list
    2. item.
    3. + Another one; this looks
    4. bad but is legal.
    5. Second paragraph of second
    6. list item.

    注意:尽管针对接续段落的「四个空白规则」是出自于官方的markdown syntax guide,但是作为对应参考用的Markdown.pl实作版本中并未遵循此一规则。所以当输入时若接续段落的缩进少于四个空白时,pandoc所输出的结果会与Markdown.pl的输出有所出入。

    在markdown syntax guide中并未明确表示「四个空白规则」是否一体适用于所有位于清单项目里的区块元素上;规范文件中只提及了段落与代码区块。但文件暗示了此规则适用于所有区块等级的内容(包含嵌套清单),并且pandoc以此方向进行解读与实作。

    有序清单

    有序清单与无序清单相类似,唯一的差别在于清单项目是以列举编号作开头,而不是项目符号。

    在原始markdown 中,列举编号是阿拉伯数字后面接着一个句点与空白。数字本身代表的数值会​​被忽略,因此下面两个清单并无差别:

    1. 1. one
    2. 2. two
    3. 3. three

    上下两个清单的输出是相同的。

    1. 5. one
    2. 7. two
    3. 1. three

    Extension: fancy_lists

    与原始markdown不同的是,Pandoc除了使用阿拉伯数字作为有序清单的编号外,也可以使用大写或小写的英文字母,以及罗马数字。清单标记可以用括号包住,也可以单独一个右括号,抑或是句号。如果清单标记是大写字母接着一个句号,句号后请使用至少两个空白字元。1

    Extension: startnum

    除了清单标记外,Pandoc 也能判读清单的起始编号,这两项资讯都会保留于输出格式中。举例来说,下面的输入可以产生一个从编号9 ​​开始,以单括号为编号标记的清单,底下还跟着一个小写罗马数字的子清单:

    1. 9) Ninth
    2. 10) Tenth
    3. 11) Eleventh
    4. i. subone
    5. ii. subtwo
    6. iii. subthree

    当遇到不同形式的清单标记时,Pandoc 会重新开始一个新的清单。所以,以下的输入会产生三份清单:

    1. (2) Two
    2. (5) Three
    3. 1. Four
    4. * Five

    如果需要预设的有序清单标记符号,可以使用#.

    1. #. one
    2. #. two
    3. #. three

    定义清单

    Extension: definition_lists

    Pandoc支援定义清单,其语法的灵感来自于PHP Markdown Extra以及reStructuredText:2

    1. Term 1
    2. : Definition 1
    3. Term 2 with *inline markup*
    4. : Definition 2
    5. { some code, part of Definition 2 }
    6. Third paragraph of definition 2.

    每个专有名词(term) 都必须单独存在于一行,后面可以接着一个空白行,也可以省略,但一定要接上一或多笔定义内容。一笔定义需由一个冒号或波浪线作开头,可以接上一或两个空白作为缩进。定义本身的内容主体(包括接在冒号或波浪线后的第一行)应该以四个空白缩进。一个专有名词可以有多个定义,而每个定义可以包含一或多个区块元素(段落、代码区块、清单等),每个区块元素都要缩进四个空白或一个tab。

    如果你在定义内容后面留下空白行(如同上面的范例),那么该段定义会被当作段落处理。在某些输出格式中,这意谓著成对的专有名词与定义内容间会有较大的空白间距。在定义与定义之间,以及定义与下个专有名词间不要留空白行,即可产生一个比较紧凑的定义清单:

    1. Term 1
    2. ~ Definition 1
    3. Term 2
    4. ~ Definition 2a
    5. ~ Definition 2b

    编号范例清单

    Extension: example_lists

    这个特别的清单标记@可以用来产生连续编号的范例清单。清单中第一个以@标记的项目会被编号为’1’,接着编号为’2’,依此类推,直到文件结束。范例项目的编号不会局限于单一清单中,而是文件中所有以@为标记的项目均会次序递增其编号,直到最后一个。举例如下:

    1. (@) My first example will be numbered (1).
    2. (@) My second example will be numbered (2).
    3. Explanation of examples.
    4. (@) My third example will be numbered (3).

    编号范例可以加上标签,并且在文件的其他地方作参照:

    1. (@good) This is a good example.
    2. As (@good) illustrates, ...

    标签可以是由任何英文字母、底线或是连字符号所组成的字串。

    紧凑与宽松清单

    在与清单相关的「边界处理」上,Pandoc与Markdown.pl有着不同的处理结果。考虑如下代码:

    1. + First
    2. + Second:
    3. - Fee
    4. - Fie
    5. - Foe
    6. + Third

    Pandoc会将以上清单转换为「紧凑清单」(在“First”, “Second”或“Third”之中没有<p>标签),而markdown则会在“Second”与“Third” (但不包含“ First”)里面置入<p>标签,这是因为“Third”之前的空白行而造成的结果。Pandoc依循着一个简单规则:如果文字后面跟着空白行,那么就会被视为段落。既然“Second”后面是跟着一个清单,而非空白行,那么就不会被视为段落了。至于子清单的后面是不是跟着空白行,那就无关紧要了。(注意:即使是设定为markdown_strict格式,Pandoc仍是依以上方式处理清单项目是否为段落的判定。这个处理方式与markdown官方语法规范里的描述一致,然而却与Markdown.pl的处理不同。)

    结束一个清单

    如果你在清单之后放入一个缩排的代码区块,会有什么结果?

    1. - item one
    2. - item two
    3. { my code block }

    问题大了!这边pandoc(其他的markdown实作也是如此)会将{ my code block }视为item two这个清单项目的第二个段落来处理,而不会将其视为一个代码区块。

    要在item two之后「切断」清单,你可以插入一些没有缩排、输出时也不可见的内容,例如HTML的注解:

    1. - item one
    2. - item two
    3. <!-​​- end of list -->
    4. { my code block }

    当你想要两个各自独立的清单,而非一个大且连续的清单时,也可以运用同样的技巧:

    1. 1. one
    2. 2. two
    3. 3. three
    4. <!-​​- -->
    5. 1. uno
    6. 2. dos
    7. 3. tres

    分隔线

    一行中若包含三个以上的* , -_符号(中间可以以空白字元分隔),则会产生一条分隔线:

    1. * * * *
    2. ---------------

    表格

    有四种表格的形式可以使用。前三种适用于等宽字型的编辑环境,例如Courier。第四种则不需要直行的对齐,因此可以在比例字型的环境下使用。

    简单表格

    Extension: simple_tables , table_captions

    简单表格看起来像这样子:

    1. Right Left Center Default
    2. ------- ------ ---------- -------
    3. 12 12 12 12
    4. 123 123 123 123
    5. 1 1 1 1
    6. Table: Demonstration of simple table syntax.

    表头与资料列分别以一行为单位。直行的对齐则依照表头的文字和其底下虚线的相对位置来决定:3

    • 如果虚线与表头文字的右侧有切齐,而左侧比表头文字还长,则该直行为靠右对齐。
    • 如果虚线与表头文字的左侧有切齐,而右侧比表头文字还长,则该直行为靠左对齐。
    • 如果虚线的两侧都比表头文字长,则该直行为置中对齐。
    • 如果虚线与表头文字的两侧都有切齐,则会套用预设的对齐方式(在大多数情况下,这将会是靠左对齐)。

    表格底下必须接着一个空白行,或是一行虚线后再一个空白行。表格标题为可选的(上面的范例中有出现)。标题需是一个以Table:(或单纯只有:)开头作为前缀的段落,输出时前缀的这部份会被去除掉。表格标题可以放在表格之前或之后。

    表头也可以省略,在省略表头的情况下,表格下方必须加上一行虚线以清楚标明表格的范围。例如:

    1. ------- ------ ---------- -------
    2. 12 12 12 12
    3. 123 123 123 123
    4. 1 1 1 1
    5. ------- ------ ---------- -------

    当省略表头时,直行的对齐会以表格内容的第一行资料列决定。所以,以上面的表格为例,各直行的对齐依序会是靠右、靠左、置中以及靠右对齐。

    多行表格

    Extension: multiline_tables , table_captions

    多行表格允许表头与表格资料格的文字能以复数行呈现(但不支援横跨多栏或纵跨多列的资料格)。以下为范例:

    1. -------------------------------------------------- -----------
    2. Centered Default Right Left
    3. Header Aligned Aligned Aligned
    4. ----------- ------- --------------- ----------------- --------
    5. First row 12.0 Example of a row that
    6. spans multiple lines.
    7. Second row 5.0 Here's another one. Note
    8. the blank line between
    9. rows.
    10. -------------------------------------------------- -----------
    11. Table: Here's the caption. It, too, may span
    12. multiple lines.

    看起来很像简单表格,但两者间有以下差别:

    • 在表头文字之前,必须以一列虚线作为开头(除非有省略表头)。
    • 必须以一列虚线作为表格结尾,之后接一个空白行。
    • 资料列与资料列之间以空白行隔开。

    在多行表格中,表格分析器会计算各直行的栏宽,并在输出时尽可能维持各直行在原始文件中的相对比例。因此,要是你觉得某些栏位在输出时不够宽,你可以在markdown 的原始档中加宽一点。

    和简单表格一样,表头在多行表格中也是可以省略的:

    1. ----------- ------- --------------- ----------------- --------
    2. First row 12.0 Example of a row that
    3. spans multiple lines.
    4. Second row 5.0 Here's another one. Note
    5. the blank line between
    6. rows.
    7. ----------- ------- --------------- ----------------- --------
    8. : Here's a multiline table without headers.

    多行表格中可以单只包含一个资料列,但该资料列之后必须接着一个空白行(然后才是标示表格结尾的一行虚线)。如果没有此空白行,此表格将会被解读成简单表格。

    格框表格

    Extension: grid_tables , table_captions

    格框表格看起来像这样:

    1. : Sample grid table.
    2. +---------------+---------------+----------------- ---+
    3. | Fruit | Price | Advantages |
    4. +===============+===============+================= ===+
    5. | Bananas | $1.34 | - built-in wrapper |
    6. | | | - bright color |
    7. +---------------+---------------+----------------- ---+
    8. | Oranges | $2.10 | - cures scurvy |
    9. | | | - tasty |
    10. +---------------+---------------+----------------- ---+

    =串成的一行区分了表头与表格本体,这在没有表头的表格中也是可以省略的。在格框表格中的资料格可以包含任意的区块元素(复数段落、代码区块、清单等等)。不支援对齐,也不支援横跨多栏或纵跨多列的资料格。格框表格可以在Emacs table mode下轻松建立。

    管线表格

    Extension: pipe_tables , table_captions

    管线表格看起来像这样:

    1. | Right | Left | Default | Center |
    2. |------:|:-----|---------|:------:|
    3. | 12 | 12 | 12 | 12 |
    4. | 123 | 123 | 123 | 123 |
    5. | 1 | 1 | 1 | 1 |
    6. : Demonstration of simple table syntax.

    这个语法与PHP markdown extra中的表格语法相同。开始与结尾的管线字元是可选的,但各直行间则必须以管线区隔。上面范例中的冒号表明了对齐方式。表头可以省略,但表头下的水平虚线必须保留,因为虚线上定义了资料栏的对齐方式。

    因为管线界定了各栏之间的边界,表格的原始码并不需要像上面例子中各栏之间保持直行对齐。所以,底下一样是个完全合法(虽然丑陋)的管线表格:

    1. fruit| price
    2. -----|-----:
    3. apple|2.05
    4. pear|1.37
    5. orange|3.09

    管线表格的资料格不能包含如段落、清单之类的区块元素,也不能包含复数行文字。

    注意:Pandoc 也可以看得懂以下形式的管线表格,这是由Emacs 的orgtbl-mod 所绘制:

    1. | One | Two |
    2. |-----+-------|
    3. | my | table |
    4. | is | nice |

    主要的差别在于以+取代了部分的|。其他的orgtbl功能并未支援。如果要指定非预设的直行对齐形式,你仍然需要在上面的表格中自行加入冒号。

    文件标题区块

    (译注:本节中提到的「标题」均指Title,而非Headers)

    Extension: pandoc_title_block

    如果档案以文件标题(Title)区块开头

    1. % title
    2. % author(s) (separated by semicolons)
    3. % date

    这部份将不会作为一般文字处理,而会以书目资讯的方式解析。(这可用在像是单一LaTeX 或是HTML 输出文件的书名上。)这个区块仅能包含标题,或是标题与作者,或是标题、作者与日期。如果你只想包含作者却不想包含标题,或是只有标题与日期而没有作者,你得利用空白行:

    1. %
    2. % Author
    3. % My title
    4. %
    5. % June 15, 2006

    标题可以包含多行文字,但接续行必须以空白字元开头,像是:

    1. % My title
    2. on multiple lines

    如果文件有多个作者,作者也可以分列在不同行并以空白字元作开头,或是以分号间隔,或是两者并行。所以,下列各种写法得到的结果都是相同的:

    1. % Author One
    2. Author Two
    3. % Author One; Author Two
    4. % Author One;
    5. Author Two

    日期就只能写在一行之内。

    所有这三个metadata 栏位都可以包含标准的行内格式(斜体、连结、脚注等等)。

    文件标题区块一定会被分析处理,但只有在--standaline ( -s )选项被设定时才会影响输出内容。在输出HTML时,文件标题会出现的地方有两个:一个是在文件的<head>区块里--这会显示在浏览器的视窗标题上--另外一个是文件的<body>区块最前面。位于<head>里的文件标题可以选择性地加上前缀文字(透过--title-prefix-T选项)。而在<body>里的文件标题会以H1元素呈现,并附带“title”类别(class),这样就能藉由CSS来隐藏显示或重新定义格式。如果以-T选项指定了标题前缀文字,却没有设定文件标题区块里的标题,那么前缀文字本身就会被当作是HTML的文件标题。

    而man page的输出器会分析文件标题区块的标题行,以解出标题、man page section number,以及其他页眉(header)页脚(footer)所需要的资讯。一般会假设标题行的第一个单字为标题,标题后也许会紧接着一个以括号包住的单一数字,代表section number(标题与括号之间没有空白)。在此之后的其他文字则为页脚与页眉文字。页脚与页眉文字之间是以单独的一个管线符号( | )作为区隔。所以,

    1. % PANDOC(1)

    将会产生一份标题为PANDOC且section为1的man page。

    1. % PANDOC(1) Pandoc User Manuals

    产生的man page 会再加上“Pandoc User Manuals” 在页脚处。

    1. % PANDOC(1) Pandoc User Manuals | Version 4.0

    产生的man page 会再加上“Version 4.0” 在页眉处。

    反斜线跳脱字元

    Extension: all_symbols_escapable

    除了在代码区块或行内代码之外,任何标点符号或空白字元前面只要加上一个反斜线,都能使其保留字面原义,而不会进行格式的转义解读。因此,举例来说,下面的写法

    1. *\*hello\**

    输出后会得到

    1. <em>*hello*</em>

    而不是

    1. <strong>hello</strong>

    这条规则比原始的markdown 规则来得好记许多,原始规则中,只有以下字元才有支援反斜线跳脱,不作进一步转义:

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

    (然而,如果使用了markdown_strict格式,那么就会采用原始的markdown规则)

    一个反斜线之后的空白字元会被解释为不断行的空白(nonbreaking space)。这在TeX的输出中会显示为~,而在HTML与XML则是显示为\\

    一个反斜线之后的换行字元(例如反斜线符号出现在一行的最尾端)则会被解释为强制换行。这在TeX的输出中会显示为\\,而在HTML里则是<br />。相对于原始markdown是以在行尾加上两个空白字元这种「看不见」的方式进行强制换行,反斜线接换行字元会是比较好的替代方案。

    反斜线跳脱字元在代码上下文中不起任何作用。

    智慧型标点符号

    Extension

    如果指定了--smart选项,pandoc将会输出正式印刷用的标点符号,像是将straight quotes转换为curly quotes 4、---转为破折号(em-dashes),--转为连接号(en -dashes),以及将...转为删节号。不断行空格(Nonbreaking spaces)将会插入某些缩写词之后,例如“Mr.”。

    注意:如果你的LaTeX template使用了csquotes套件,pandoc会自动侦测并且使用\enquote{...}在引言文字上。

    行内格式

    强调

    强调某些文字,只要以*_符号前后包住即可,像这样:

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

    重复两个*_符号以产生更强烈的强调

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

    一个前后以空白字元包住,或是前面加上反斜线的*_符号,都不会转换为强调格式:

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

    Extension: intraword_underscores

    因为_字元有时会使用在单字或是ID之中,所以pandoc不会把被字母包住的_解读为强调标记。如果有需要特别强调单字中的一部分,就用*

    1. feas*ible*, not feas*able*.

    删除线

    Extension: strikeout

    要将一段文字加上水平线作 ​​为删除效果,将该段文字前后以~~包住即可。例如,

    1. This ~~is deleted text.~~

    上标与下标

    Extension: superscript , subscript

    要输入上标可以用^字元将要上标的文字包起来;要输入下标可以用~字元将要下标的文字包起来。直接看范例,

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

    如果要上标或下标的文字中包含了空白,那么这个空白字元之前必须加上反斜线。(这是为了避免一般使用下的~^在非预期的情况下产生出意外的上标或下标。)所以,如果你想要让字母P后面跟着下标文字’a cat’,那么就要输入P~a\ cat~,而不是P~a cat~

    字面文字

    要让一小段文字直接以其字面形式呈现,可以用反引号将其包住:

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

    如果字面文字中也包含了反引号,那就使用双重反引号包住:

    1. Here is a literal backtick `` ` ``.

    (在起始反引号后的空白以及结束反引号前的空白都会被忽略。)

    一般性的规则如下,字面文字区段是以连续的反引号字元作为开始(反引号后的空白字元为可选),一直到同样数目的反引号字元出现才结束(反引号前的空白字元也为可选)。

    要注意的是,反斜线跳脱字元(以及其他markdown 结构)在字面文字的上下文中是没有效果的:

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

    Extension: inline_code_attributes

    与围栏代码区块一样,字面文字也可以附加属性:

    1. `<$>`{.haskell}

    数学

    Extension: tex_math_dollars

    所有介于两个$字元之间的内容将会被视为TeX数学公式处理。开头的$右侧必须立刻接上任意文字,而结尾$的左侧同样也必须紧挨着文字。这样一来,$20,000 and $30,000就不会被当作数学公式处理了。如果基于某些原因,有必须使用$符号将其他文字括住的需求时,那么可以在$前使用反斜线跳脱字元,这样$就不会被当作数学公式的分隔符。

    TeX 数学公式会在所有输出格式中印出。至于会以什么方式演算编排(render) 则取决于输出的格式:

    Markdown, LaTeX, Org-Mode, ConTeXt

    公式会以字面文字呈现在两个$符号之间。

    reStructuredText

    公式会使用此处所描述的:math:这个“interpreted text role”来进行演算编排。

    AsciiDoc

    公式会以latexmath:[...]演算编排。

    Texinfo

    公式会在@math指令中演算编排。

    groff man

    公式会以去掉$后的字面文字演算编排。

    MediaWiki

    公式会在<math>标签中演算编排。

    Textile

    公式会在<span class="math">标签中演算编排。

    RTF, OpenDocument, ODT

    如果可以的话,公式会以unicode 字元演算编排,不然就直接使用字面字元。

    Docbook

    如果使用了--mathml旗标,公式就会在inlineequationinformalequation标签中使用mathml演算编排。否则就会尽可能使用unicode字元演算编排。

    Docx

    公式会以OMML 数学标记的方式演算编排。

    FictionBook2

    如果有使用--webtex选项,公式会以Google Charts或其他相容的网路服务演算编排为图片,并下载嵌入于电子书中。否则就会以字面文字显示。

    HTML, Slidy, DZSlides, S5, EPUB

    公式会依照以下命令列选项的设置,以不同的方法演算编排为HTML 代码。

    1. 预设方式是将TeX数学公式尽可能地以unicode字元演算编排,如同RTF、DocBook以及OpenDocument的输出。公式会被放在附有属性class="math"span标签内,所以可以在需要时给予不同的样式,使其突出于周遭的文字内容。

    2. 如果使用了--latexmathml选项,TeX数学公式会被显示于$$$字元中,并放在附带LaTeX类别的<span>标签里。这段内容会用LaTeXMathML script演算编排为数学公式。(这个方法无法适用于所有浏览器,但在Firefox中是有效的。在不支援LaTeXMathML的浏览器中,TeX数学公式会单纯的以两个$字元间的字面文字呈现。)

    3. 如果使用了--jsmath选项,TeX数学公式会放在<span>标签(用于行内数学公式)或<div>标签(用于区块数学公式)中,并附带类别属性math。这段内容会使用jsMath script来演算编排。

    4. 如果使用了--mimetex选项,mimeTeX CGI script会被呼叫来产生每个TeX数学公式的图片。这适用于所有浏览器。--mimetex选项有一个可选的URL参数。如果没有指定URL,它会假设mimeTeX CGI script的位置在/cgi-bin/mimetex.cig

    5. 如果使用了--gladtex选项,TeX数学公式在HTML的输出中会被<eq>标签包住。产生的htex档案之后可以透过gladTeX处理,这会针对每个数学公式生成图片,并于最后生成一个包含这些图片连结的html档案。所以,整个处理流程如下:

      pandoc -s —gladtex myfile.txt -o myfile.htex
      gladtex -d myfile-images myfile.htex

      produces myfile.html and images in myfile-images

    6. 如果使用了--webtex选项,TeX数学公式会被转换为<img>标签并连结到一个用以转换公式为图片的外部script。公式将会编码为URL可接受格式并且与指定的URL参数串接。如果没有指定URL,那么将会使用Google Chart API (http://chart.apis.google.com/chart?cht=tx&chl= )。

    7. 如果使用了--mathjax选项,TeX数学公式将会被包在\(...\)(用于行内数学公式)或\[...\](用于区块数学公式)之间显示,并且放在附带类别math<span>标签之中。这段内容会使用MathJax script演算编排为页面上的数学公式。

    Raw HTML

    Extension: raw_html

    Markdown允许你在文件中的任何地方插入原始HTML(或DocBook)指令(除了在字面文字上下文处,此时的< , >&都会按其字面意义显示)。(技术上而言这不算扩充功能,因为原始markdown本身就有提供此功能,但做成扩充形式便可以在有特殊需要的时候关闭此功能。)

    输出HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown 以及Textile 等格式时,原始HTML 代码会不作修改地保留至输出档案中;而其他格式的输出内容则会将原始HTML 代码去除掉。

    Extension: markdown_in_html_blocks

    原始markdown允许你插入HTML「区块」:所谓的HTML区块是指,上下各由一个空白行所隔开,开始与结尾均由所在行最左侧开始的一连串对称均衡的HTML标签。在这个区块中,任何内容都会当作是HTML来分析,而不再视为markdown;所以(举例来说),*符号就不再代表强调。

    当指定格式为markdown_strict时,Pandoc会以上述方式处理;但预设情况下,Pandoc能够以markdown语法解读HTML区块标签中的内容。举例说明,Pandoc能够将底下这段

    1. <table>
    2. <tr>
    3. <td>*one*</td>
    4. <td>[a link](http://google.com)</td>
    5. </tr>
    6. </table>

    转换为

    1. <table>
    2. <tr>
    3. <td><em>one</em></td>
    4. <td><a href="http://google.com">a link</a></td>
    5. </tr>
    6. </table>

    Markdown.pl则是保留该段原样。

    这个规则只有一个例外:那就是介于<script><style>之间的文字都不会被拿来当作markdown解读。

    这边与原始markdown的分歧,主要是为了让markdown能够更便利地混入HTML区块元素。比方说,一段markdown文字可以用<div>标签将其前后包住来进行样式指定,而不用担心里面的markdown不会被解译到。

    Raw TeX

    Extension: raw_tex

    除了HTML 之外,pandoc 也接受文件中嵌入原始LaTeX, TeX 以及ConTeXt 代码。行内TeX 指令会被保留并不作修改地输出至LaTeX 与ConTeXt 格式中。所以,举例来说,你可以使用LaTeX 来导入BibTeX 的引用文献:

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

    请注意在LaTeX 环境下时,像是底下

    1. \begin{tabular}{|l|l|}\hline
    2. Age & Frequency \\ \hline
    3. 18--25 & 15 \\
    4. 26--35 & 33 \\
    5. 36--45 & 22 \\ \hline
    6. \end{tabular}

    位在beginend标签之间的内容,都会被当作是原始LaTeX资料解读,而不会视为markdown。

    行内LaTeX 在输出至Markdown, LaTeX 及ConTeXt 之外的格式时会被忽略掉。

    LaTeX 巨集

    Extension: latex_macros

    当输出格式不是LaTeX时,pandoc会分析LaTeX的\newcommand\renewcommand定义,并套用其产生的巨集到所有LaTeX数学公式中。所以,举例来说,下列指令对于所有的输出格式均有作用,而非仅仅作用于LaTeX格式:

    1. \newcommand{\tuple}[1]{\langle #1 \rangle}
    2. $\tuple{a, b, c}$

    在LaTeX的输出中,\newcommand定义会单纯不作修改地保留至输出结果。

    连结

    Markdown 接受以下数种指定连结的方式。

    自动连结

    如果你用角括号将一段URL 或是email 位址包起来,它会自动转换成连结:

    1. <http://google.com>
    2. <sam@green.eggs.ham>

    行内连结

    一个行内连结包含了位在方括号中的连结文字,以及方括号后以圆括号包起来的URL。(你可以选择性地在URL 后面加入连结标题,标题文字要放在引号之中。)

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

    方括号与圆括号之间不能有空白。连结文字可以包含格式(例如强调),但连结标题则否。

    参考连结

    一个明确的参考连结包含两个部分,连结本身以及连结定义,其中连结定义可以放在文件的任何地方(不论是放在连结所在处之前或之后)。

    连结本身是由两组方括号所组成,第一组方括号中为连结文字,第二组为连结标签。(在两个方括号间可以有空白。)连结定义则是以方括号框住的连结标签作开头,后面跟着一个冒号一个空白,再接着一个URL,最后可以选择性地(在一个空白之后)加入由引号或是圆括号包住的连结标题。

    以下是一些范例:

    1. [my label 1]: /foo/bar.html "My title, optional"
    2. [my label 2]: /foo
    3. [my label 3]: http://fsf.org (The free software foundation)
    4. [my label 4]: /bar#special 'A title in single quotes'

    连结的URL 也可以选择性地以角括号包住:

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

    连结标题可以放在第二行:

    1. [my label 3]: http://fsf.org
    2. "The free software foundation"

    需注意连结标签并不区分大小写。所以下面的例子会建立合法的连结:

    1. Here is [my link][FOO]
    2. [Foo]: /bar/baz

    在一个隐性参考连结中,第二组方括号的内容是空的,甚至可以完全地略去:

    1. See [my website][], or [my website].
    2. [my website]: http://foo.bar.baz

    注意:在Markdown.pl以及大多数其他markdown实作中,参考连结的定义不能存在于嵌套结构中,例如清单项目或是区块引言。Pandoc lifts this arbitrary seeming restriction。所以虽然下面的语法在几乎所有其他实作中都是错误的,但在pandoc中可以正确处理:

    1. > My block [quote].
    2. >
    3. > [quote]: /foo

    内部连结

    要连结到同一份文件的其他章节,可使用自动产生的ID(参见HTML, LaTeX与ConTeXt的标题识别符一节后半)。例如:

    1. See the [Introduction](#introduction).

    或是

    1. See the [Introduction].
    2. [Introduction]: #introduction

    内部连结目前支援的格式有HTML(包括HTML slide shows 与EPUB)、LaTeX 以及ConTeXt。

    图片

    在连结语法的前面加上一个!就是图片的语法了。连结文字将会作为图片的替代文字(alt text):

    1. ![la lune](lalune.jpg "Voyage to the moon")
    2. ![movie reel]
    3. [movie reel]: movie.gif

    附上说明的图片

    Extension: implicit_figures

    一个图片若自身单独存在一个段落中,那么将会以附上图片说明(caption)的图表(figure)形式呈现。5(在LaTeX中,会使用图表环境;在HTML中,图片会被放在具有figure类别的div元素中,并会附上一个具有caption类别的p元素。)图片的替代文字同时也会用来作为图片说明。

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

    如果你只是想要个一般的行内图片,那么只要让图片不是段落里唯一的元素即可。一个简单的方法是在图片后面插入一个不断行空格:

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

    脚注

    Extension: footnotes

    Pandoc’s markdown 支援脚注功能,使用以下的语法:

    1. Here is a footnote reference,[^1] and another.[^longnote]
    2. [^1]: Here is the footnote.
    3. [^longnote]: Here's one with multiple blocks.
    4. Subsequent paragraphs are indented to show that they
    5. belong to the previous footnote.
    6. { some.code }
    7. The whole paragraph can be indented, or just the first
    8. line. In this way, multi-paragraph footnotes work like
    9. multi-paragraph list items.
    10. This paragraph won't be part of the note, because it
    11. isn't indented.

    脚注参考用的ID 不得包含空白、tabs 或换行字元。这些ID 只会用来建立脚注位置与脚注文字的对应关连;在输出时,脚注将会依序递增编号。

    脚注本身不需要放在文件的最后面。它们可以放在文件里的任何地方,但不能被放入区块元素(清单、区块引言、表格等)之中。

    Extension: inline_notes

    Pandoc 也支援了行内脚注(尽管,与一般脚注不同,行内脚注不能包含多个段落)。其语法如下:

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

    行内与一般脚注可以自由交错使用。

    引用

    Extension: citations

    Pandoc能够以数种形式自动产生引用与参考书目(使用Andrea Rossato的hs-citeproc)。为了使用这项功能,你需要一个下列其中一种格式的参考书目资料库:

    FormatFile extension

    MODS .mods

    BibLaTeX .bib

    BibTeX .bibtex

    RIS .ris

    EndNote .enl

    EndNote XML .xml

    ISI .wos

    MEDLINE .medline

    Copac .copac

    JSON citeproc.json

    需注意的是副档名.bib一般而言同时适用于BibTeX与BibLaTeX的档案,不过你可以使用.bibtex来强制指定BibTeX。

    你需要使用命令列选项--bibliography来指定参考书目档案(如果有多个书目档就得反覆指定)。

    预设情况下,pandoc会在引用文献与参考书目中使用芝加哥「作者-日期」格式。要使用其他的格式,你需要用--csl选项来指定一个CSL 1.0格式的档案。关于建立与修改CSL格式的入门可以在http://citationstyles.org/downloads/primer.html这边找到。https://github.com/citation-style-language/styles是​​CSL格式的档案库。也可以在http://zotero.org/styles以简单的方式浏览。

    引用资讯放在方括号中,以分号区隔。每一条引用都会有个key,由@加上资料库中的引用ID组成,并且可以选择性地包含前缀、定位以及后缀。以下是一些范例:

    1. Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].
    2. Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
    3. Blah blah [@smith04; @doe99].

    @前面的减号( - )将会避免作者名字在引用中出现。这可以用在已经提及作者的文章场合中:

    1. Smith says blah [-@smith04].

    你也可以在文字中直接插入引用资讯,方式如下:

    1. @smith04 says blah.
    2. @smith04 [p. 33] says blah.

    如果引用格式档需要产生一份引用作品的清单,这份清单会被放在文件的最后面。一般而言,你需要以一个适当的标题结束你的文件:

    1. last paragraph...
    2. # References

    如此一来参考书目就会被放在这个标题后面了。


    1. 之所以有这条规则,主要是要避免以人名头文字缩写作为开头的段落所带来的混淆,像是

      B. Russell was an English philosopher.

    这样就不会被当作清单项目了。

    这条规则并不会避免以下

    1. (C) 2007 Joe Smith

    这样的叙述被解释成清单项目。在这情形下,可以使用反斜线:

    1. (C\) 2007 Joe Smith

    1. David Wheeler对于markdown的建议也同时影响了我。↩

    2. 这个方案是由Michel Fortin在Markdown discussion list的讨论中所提出。↩

    3. 译注:straight quotes指的是左右两侧都长得一样的引号,例如我们直接在键盘上打出来的单引号或双引号;curly quotes则是左右两侧不同,有从两侧向内包夹视觉效果的引号。↩

    4. 这项功能尚未在RTF, OpenDocument或ODT格式上实现。在这些格式中,你会得到一个在段落中只包含自己的图片,而无图片说明。↩