8773 字

Pandoc 中的 Markdown 语法 z

2016/10/26
计算机 - 软件应用; Markdown; Pandoc;

原文地址：

  1. http://www.cnblogs.com/baiyangcao/p/pandoc_markdown.html
  2. http://www.bagualu.net/wordpress/archives/5284

1 小技巧汇总

  1. 博客中提供的 <pre class="white">...</pre> 和 <pre class="center">...</pre> 只能通过 html 实现；
  2. 普通的 <pre><code>...</code></pre> 通过缩进 4 个空格实现；
  3. 块级的代码高亮通过 ```…``` 方法实现，其中的 ` 可以被替换成~，并且可以添加 class, id, 代码的语言名称 等内容；
  4. 行内代码通过 ` 来包括，也可以通过 <code>...</code> 来实现，生成标题 class, id, 代码的语言名称 的方法与块级代码类似；
  5. <hn> 也可以添加 class, id 等；
  6. 在行内代码块中显示 ` 需要用 ` ` `，在行间高亮代码中显示 ```，只需要将 ` 替换成 ~ 就可以，不需要用 RMarkdown 中的做法；
  7. 现在通过 Pandoc 解释 Hexo 下的 Markdown，基本上可以保证解释的结果能够与 Mathjax 良好兼容，但要注意 Pandoc 对 LaTeX 语法的支持中，行内公式和行间公式分别用 `$...$` 和 `$$ $$` 完成，不支持使用 “\(...\)” 和 “\[...\]” 语法，当然 “\begin{equation}...\end{equation}” 还是可以正常使用的；
  8. 脚注的语法是 ^[]，另外一种脚注内容单独放置的语法暂时不使用；
  9. 删除线用一对 ~~ 实现，上标用一对 ^ 实现，下标用一对 ~ 实现；
  10. 使用 > 生成块级内容时，空行最好也添加上 >，这样在原始的 Markdown 规范和 Pandoc 的扩展规范中都能正常工作；

2 概述

Pandoc 中支持扩展修订版本的 Markdown 语法

  • 使用 Pandoc 中支持的 Markdown 语法用 -f markdown；
  • 使用标准 Markdown 语法用 -f markdown_strict；

Pandoc 所支持的语法各种对标准 Markdown 语法的扩展可以通过在格式后以 +EXTENSION 添加或 -EXTENSION 去除，如：

  • -f markdown-footnotes 表示识别除了 footnotes 扩展之外的所有 Pandoc Markdown 语法；
  • -f markdown_strict+footnotes+pipe_tables 表示识别标准 Markdown 语法加上 footnotes 和 pipe_tables 扩展语法。

3 段落

段落是指一个或多个空行之后的多行文本，文本中的换行都被视作空格，如若要输出换行，则应在行末添加两个或多个空格

注： 段落之后也应加一个空行，以区分段落和其他部分，如：列表。

如下Markdown语法

这是一个段落
 - 列表项1
 - 列表项2

翻译成HTML如下：

这是一个段落  - 列表项1  - 列表项2

若要正确的显示列表应在段落后添加一个空行，如下：

这是一个段落

 - 列表项1
 - 列表项2

3.1 段落和换行符

段落之间有一个空行。如果没有空行，那么它们会被认为是一个段落。同一个段落中不同的行之间的换行符会被一个空格代替。这个对于中文而言，造成的后果是，段落中会莫名其妙的多出几个空格，看着奇怪。Pandoc 中有一个扩展能自动处理这种换行符，这个扩展叫east_asian_line_breaks，这个扩展在 Pandoc 中没有被缺省的打开，所以需要手动打开，即使用-from markdown+east_asian_line_breaks，这个扩展是在 Pandoc 的 1.16 版本中实现，此前的版本中是没有这个扩展的。因此，如果你使用这个扩展是发现这个扩展不认识，那你需要升级你的 Pandoc 的版本。

一行结束时，如果要强制换行，可以在行尾输入两个及以上空格。不然，Pandoc 会以上面的方式进行段内换行的处理。一种可能的例外是写多行诗时，一个小块可能以<br />的形式放在一起，之后又用一个<p>开始一个新的小块，也许后面的行文本块方法是一种可行的做法，或者在一行结尾处用\来达到目的。

| 咏梅
| 啊！梅花
|   红
| 
|       霜

一行一行一行\
二行二行二行

三行三行三行

3.2 Extension: escaped_line_breaks

也可以通过在行末添加一个反斜线\来换行1，如：

这是第一行\
这是第二行

4 标题

Pandoc中支持两种标题语法：Setext 和 ATX。

4.1 Setext 风格语法

setext 风格标题是一行文本下跟一行=符号（表示一级标题）和-符号（表示二级标题），文本中可以包含如斜体、加粗等行内格式2

一级标题
=======

二级标题
-------

4.2 ATX 风格语法

ATX 风格标题就是我们通常所用的 Markdown 标题语法，在行首添加一到六个#符号表示不同级别的标题，编译成对应的 html 标签<hn>，如一个#表示一级标题，会编译成 HTML 标签<h1>，与 setext 风格相同，文本中可以包含如斜体、加粗等行内格式。

4.2.1 Extension: blank_before_header

标准 Markdown 语法并不要求在标题前添加一个空行，但是 Pandoc 语法却要求标题前添加一个空行（除了文档开头）

4.2.2 标题标识符 Extension: header_attributes

通常在 html 和 LaTeX 中使用，可以通过在标题行末添加如下形式的标识符来为标题添加属性：

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

其中的id是最有用的，通常用于文内的交叉引用。使用id做文内引用的方法是[标题名](#id)，这样在生成的 html 和 pdf 文档中就会有到这个标题的超链了。其中的标题名不必要和该标题的名字一样，只要保证#id一样就可以了。

identifier会被编译成 html 文档中的id属性，class会被合并成 html 文档中的class属性

4.2.3 Extension: auto_identifiers

没有显示指定identifier的标题会根据标题内容自动分配一个唯一标识，标题文本生成identifier的顺序如下：

  1. 移除格式、连接等；
  2. 移除脚注(footnotes)；
  3. 移除除了下划线_和连接符-之外的标点符号；
  4. 用连接符-替换所有空格和换行符；
  5. 将所有字母转换成小写；
  6. identifier不能以数字和标点符号开头；
  7. 如果文本此时为空，则取section做标识符；
  8. 如果自动生成的标识符相同则根据顺序在标识符后添加-1、-2等。

4.2.4 Extension: implicit_header_references

Pandoc 默认每个标题都定义了引用链接，故对于标题# 标题1，可以使用[标题1]或者[标题1][]引用，注意，引用链接是区分大小写的。

5 块引用

块引用是指一个或多个段落或其他块元素（如列表或标题），每一行以一个>符号和一个可选的空格开头（注意：>符号并不需要在行首，但是不可缩进超过三个空格）

> 块引用
> 段落
> 
> 1. 列表1
> 2. 列表2

块引用并不是每一行都需要以>符号开头，只需在每一个区域的首行添加>即可，如下文本和上述的文本有相同的效果。

警告：实际上在本博客的设置下后一种情形出现了两个 block，即两种情形下的显示结果并不相同，这显然与 Pandoc 的blank_before_blockquote扩展有关。因此保险起见，还是推荐使用第一种方式的块引用。另一种可以考虑的解决方法是使用标准的 Markdown，但是根据需要加上少量 Pandoc 的特有扩展，这样可以保证两种情形的效果相同。

> 块引用
段落

> 1. 列表1
2. 列表2

注： 1. 块引用可以嵌套使用； 2. >后的空格作为块引用标识的一部分，若是在块引用中添加代码， 则需在>后添加五个空格。

5.1 Extension: blank_before_blockquote

标准 Markdown 语法并不要求在块引用前添加一个空行，但是 Pandoc 语法却要求在块引用前添加一个空行（除了文档开头外）。

6 代码块{codeChunck}

6.1 缩进式代码块{tab-codeChunck}

由四个空格或一个tab缩进的文本取做代码块，区块中的特殊字符、空格和换行都会被保留，而缩进的空格和tab会在输出中移除，但在代码块中的空行不必缩进

    using System;

    public class Program
    {
        public static void Main() 
        {
            Console.Write('Hello World!');
        }
    }

6.2 围栏式代码块

6.2.1 Extension: fenced_code_blocks

除了标准的缩进式代码块之外，Pandoc 还支持围栏式代码块， 代码块以三个或三个以上的~符号行开始，以等于或多于开始行~个数符号行结束， 若是代码块中含有~，只需使开始行和结束行中的~符号个数多于代码块中的即可

~~~~~
~~~~
code here
~~~~
~~~~~~

6.2.2 Extension: backtick_code_blocks

与fenced_code_blocks相同，只不过使用反引号`替换波浪线~而已

6.2.3 Extension: fenced_code_attributes

与标题标识符相同，在波浪线或反引号代码块的首行添加属性即可，如下：

~~~ { #id .cs .numberLines }
using System;

public class Program
{
    public static void Main() 
    {
        Console.Write('Hello World!');
    }
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

如上代码中添加的 cs 类可以用于代码 HTML 和 LaTex 输出的代码高亮，Pandoc 所支持高亮的语言可以通过在命令行中输入pandoc --version查看， 除了上述方式设置代码块的高亮语言，也可通过如下方式设置

```cs
using System;

public class Program
{
    public static void Main() 
    {
        Console.Write('Hello World!');
    }
}
```

7 行文本块

7.1 Extension: line_blocks

行文本块是指一系列由|和一个空格开头的行，在输出中可以保留空格和换行， 不会像段落那样将换行符转换成空格，可用于诗文和地址的排版

| 咏梅
| 啊！梅花
|   红
| 
|       霜

8 列表

8.1 无序列表

列表项以星号*、加号+或减号-开头，如下：

 * 列表项1
 * 列表项2
 * 列表项3

这样输出的列表是紧凑型的列表，若是要输出宽松型列表， 可在列表项之间添加空行即可

 * 列表项1

 * 列表项2

 * 列表项3

8.1.1 四空格原则{4-spaces-rule}

一个列表项里可以包含多个段落或其他块级别内容， 但是其次的段落都应该以一个空行和四个空格缩进开始

  * 列表项1 第一段落

    列表项1 第二段落

  * 列表项2 第一段落

        { code }

列表中可以嵌套列表，每一层嵌套列表都需要添加四个空格或一个tab缩进， 并且每一层应该使用不同的起始符。

 * 1.1
     + 1.1.1
        - 1.1.1.1
        - 1.1.1.2
     + 1.1.2
 * 1.2

8.2 有序列表{ordered-lists}

有序列表项以数字、一个点.和一个空格开头， 并且取第一个列表项数字为基准，依次向下排，故下面两个列表是一样的

**列表1**

 1. 一
 2. 二
 3. 三

---

**列表2**

 1. 一
 5. 二
 9. 三

8.2.1 Extension: fancy_lists

不像标准 Markdown 语法只能使用阿拉伯数字作为有序列表标识， Pandoc中还支持大小写字母、罗马数字，或用括号、右括号标识列表项， 但其后的文本需与列表标识隔开至少一个空格， 若是一个大写字母和一个点做标识，则需在其后跟两个空格。

fancy_lists扩展还支持使用#来代替数字

 #. 列表项1
 #. 列表项2

8.2.2 Extension: startnum

Pandoc 支持自定义的列表起始数字，而且会在每次使用不同的列表标识便重新开始一个新列表， 如下会创建三个列表

 (3) 列表1项1
 (7) 列表1项2
  1. 列表2项1
  *  列表2项1

8.3 定义列表（dl, dt, dd 等）

8.3.1 Extension: definition_lists

词语1

 :    词语1的定义

    词语1的第二段定义
第二段定义是多行的

词语2

 :    词语2的定义

定义列表形式如上，术语独占一行，其后可以跟一个空行，然后是一个或多个定义，每一个定义以:和~开头，可以缩进一到两个空格。

一个术语可以包含多个定义，一个定义可以包含多个区块（段落、代码块、列表等），而每一个区块都应以四个空格或一个tab缩进。

8.4 编号列表{numbered-lists}

8.4.1 Extension: example_lists

特殊的列表标识符@用于连续编号列表，整个文档中的@符号从1开始编号， 依次类推，如下的前三个@会分别替换为1, 2, 3

(@)  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, ...

@ 后可以加上一个字符串来表示一个标签，用于在其他地方引用这个序号，如上例中的 @good 会被 4 来替换。

8.5 紧凑和宽松列表

若列表项前插入一个空行，则会将当前列表项作为段落处理（用<p>标签包裹），从而输出“宽松”的列表，反之则会输出“紧凑”的列表。

8.6 截断列表

 1. 列表1项1
 2. 列表1项2

 1. 列表2项1
 2. 列表2项2

如上想要输出两个列表，却会输出一个有四项的列表，要想“截断”列表1，则可在两个列表之间插入一行没有缩进的行，如 HTML 注释

 1. 列表1项1
 2. 列表1项2

<!-- -->

 1. 列表2项1
 2. 列表2项2

9 水平线

一行由三个或三个以上*、-或_组成的会输出一个水平线。

10 表格

Pandoc 中支持 simple_tables, multiline_tables, grid_tables 和 pipe_tables 四种表格。要注意单元格中内容的换行与块元素是不同的概念，原始内容可以换行与显示结果中的换行是不同的概念。

10.1 Extension: table_captions

四种表格都可以通过在表格前或后添加一个以Table:（或:）开头的段落表示表格的表头。

10.2 Extension: simple_tables（不推荐）

简单的表格形如下

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

Table:  简单表格实例

列首行和表格中的每一行都应独占一行，列对齐方式由列头和其下虚线行的相对位置决定：

  • 右对齐： 虚线行与列头右对齐，而左端超过列头
  • 左对齐： 虚线行与列头左对齐，而右端超过列头
  • 居中： 虚线行超出列头两端
  • 默认： 虚线行与列头两端对齐（一般情况下默认是左对齐）

表格必须以一个空行或一行虚线行加一个空行结束，而且有时可以忽略列头行。

注：中文环境不推荐使用这种方式选择对齐方式，反正小生是玩不好。

10.3 Extension: multiline_tables（支持对齐、原始内容换行）

跨行表格允许列首行和表格中的行可以分多行撰写，但是不支持单元格的跨行和跨列，跨行表格必须以一行虚线行开始，以一行虚线行和一个空行结束，行与行之间应有一个空行

-------------------------------------------------------------
 Centered   Default           Right Left
  Header    Aligned         Aligned Aligned
----------- ------- --------------- -------------------------
   First    row                12.0 一个行跨
                                    多行的例子

  Second    row                 5.0 这是另一行
                                    注意表格行与行
                                    之间的空行哦~~
-------------------------------------------------------------

Table: 这个是标题
也能跨行的啦~~

跨行表格的列首行也可以被忽略，也可以只包含一行，但是这一行后必须跟着一个空行

10.4 Extension: grid_tables（支持块元素）

网格表格中列首行与其他行需要使用一行=隔开，但是在没有列首行的表格中可以忽略，网格表格中的单元格可以包含任意区块（段落、代码块、列表等），但对齐方式和单元格的跨行跨列都是不支持滴~

: 网格表格样例

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

10.5 Extension: pipe_tables（支持对齐）

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

  : `pipe_tables`表格样例

pipe_tables 每一列之间用竖线|隔开，列首行和其余行之间用虚线行隔开，虚线行中用冒号:来决定列的对其方式，表格中两端的|竖线列可以忽略，而且|只是用来隔开列，而不必对齐，但是 pipe_tables 的列首行不能忽略，要是想要生成没有列首的表格，只要在列首行的单元格置空便可

 | 
-----|-----:
苹果 | 2.05
梨   | 1.37
橘子 | 3.09

注： pipe_tables 中的单元格不可包含如段落、列表等区块元素

11 反斜线转义符

11.1 转义符

11.1.1 Extension: all_symbols_escapable

除了在代码块和行内代码中，反斜线后的任何字符和空格都会按照字面输出，Markdown 语法中能被转义的字符如下

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

12 行内格式

12.1 强调

用一个 * 或 _ 包裹起来的文本会被输出为斜体，而用一对 ** 或 __ 包裹起来的文本会被输出为 加粗。

强调文本：这里是*斜体*，这里是**加粗**

若是 * 或 _ 符号前后有 空格，或用 \ 转义，则不会输出为斜体或加粗。

这里 * 不会被翻译成斜体 *, 而且 \*这里也不会\*。

12.1.1 Extension: intraword_underscores

文本中的成对_不会被翻译成斜体， 这个扩展的意思是 Pandoc 不会把文字中间的_解释为加粗的语法，因为 Pandoc 认为在文字中使用_是一个普遍的现象。如果解释为加粗反而会带来不便，因此如果要在文字中间使用强调（加粗）语法，请使用*。

12.2 删除线

12.2.1 Extension: strikeout

一对~~所包裹的文本会添加一条删除线

~~这个文本被删除了~~

12.3 上标和下标

12.3.1 Extension: superscript, subscript

上标可以通过一对^标识，而下标可以通过一对~标识， 若上下标中包含空格，可以通过\转义空格

H~2~O
2^10^ = 1024
P~a\ cat~

12.4 行内代码块

小段的行内代码块可以使用一对`包裹， 而行内代码块中含有反引号`，可以用双反引号包裹代码块， 但是行内代码块中的转义符\没有转义的作用。

这是一个`行内代码块`
这是一个行内代码块的反引号`` ` ``
这是一个行内代码块的反引号` ` `，效果与上一行在本博客中类似
这是一个行内代码块的反斜线`\`

12.4.1 Extension: inline_code_attributes

与代码块一样，行内代码块后写可以添加属性，形式如下：

`行内代码块`{ #identifier .class key=value }

13 HTML 代码

13.1 Extension: raw_html

可以直接在文档中插入 HTML 代码（除了代码块等<, >和&符不会被翻译的地方之外）

13.2 Extension: markdown_in_html_blocks

使用 markdown_strict 格式的时候，HTML 代码中的 Markdown 语法不会被翻译， 但是使用 Pandoc 的 Markdown 格式时，HTML 代码中的 Markdown 语法也会被翻译， 但是有一个例外，HTML 代码<script>和<style>标签中的 Markdown 语法也不会被翻译。

15 脚注

15.1 Extension: footnotes

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.

脚注的identifier不可包含空格，tab或换行， 在输出中脚注会按照顺序编号，如上例中的[^longnote]会被编号2， 脚注虽不必一定放在文档的末尾，但也不可以出现在其他的区块中（如列表、块引用、表格等）3。

16 元数据块

这一小部分内容可以在后面学习过 Pandoc 模板以后在来看。

在 Markdown 中可以嵌入元数据块，这些块用来给定文档的一些属性，这些块分为两种，一种是使用在文章最前面的标题块，还有一种是使用在文中任意地方的，叫YAML 块，分别介绍如下：

16.1 标题块 Extension: pandoc_title_block

这个块放在文件的最前面，格式如下

% 标题
% 作者，多个作者使用分号分开
% 日期

这样的内容将会被解析，解析的结果可能会出现在最后的文档中（比如在 pdf 或者 html 的标题以及作者部分，之所以说“可能”，是因为自定义模板中可能没有这些输出）。这三个元素也可以只有其中一个或者两个，在这种情况下，在相应的地方要留出空行，比如

% 我的标题
%
% 2016年4月6日

标题以及作者可以是多行的，第二行以后的文字需要缩进。多个作者可使用分号分开，也可使用多行格式，例如：

% 我的标题
  多行的标题
% 作者1
  作者2
% 2016年4月6日

日期必须在一行，不能分行。

关于这些元素在最后输出文件中的位置，可以参考后面的 Pandoc 模板部分。

16.2 YAML 元数据 Extension: yaml_metadata_block

yaml 块是用---开头，以---或者...结束的一个块，这中块可以出现在文中的任何地方，每个块开始的地方，必须在前面留出一个空行。yaml 块也可以放在一个独立的文件中，在使用 Pandoc 的时候，把这个 yaml 文件作为输入就可以了。Pandoc 在处理多个输入文件的时候，总是把这些文件合成一个文件，然后再进行处理，因此一个单独的 yaml 文件是不会有问题的。但是请注意一定要以---把 yaml 块包起来。

下面是一个处理独立 yaml 文件的命令行

pandoc aa.md metadata.yaml -s -o aa.html

yaml 块中定义的变量会加入到文件的 metadata 中。如果一个变量被多个块定义，那么它的值为第一个被定义的地方，后面的定义无效。另外如果一个变量以下划线结束，它将不会被 pandoc 处理。

下面是一个元数据块的例子，第一行中包含:，因此需要一个引号包起来，在 abstract 定义中，使用|来开始一个缩进的块。

---
title:  'This is the title: it contains a colon'
author:
- name: Author One
  affiliation: University of Somewhere
- name: Author Two
  affiliation: University of Nowhere
tags: [nothing, nothingness]
abstract: |
  This is the abstract.

  It consists of two paragraphs.
...

在上面的这个块中，作者部分有自定义的域，因此需要一个自定义的模板来显示它们，下面是一个模板的例子：

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

16.3 引用 Extansion: citation

这是关于如何添加参考文献的内容。

17 YAML 语法简单介绍

前面提到了 Markdown 中的元数据块可以通过 YAML 语法来指定。

YAML 全称为（Yet Another Markup Language），也是一种标签语言。是以数据为表达目标的语言。通过空格和分行来分隔数据单元。下面是一个实例：

house:
  family:
    name: Doe
    parents:
      - John
      - Jane
    children:
      - Paul
      - Mark
      - Simone
  address:
    number: 34
    street: Main Street
    city: Nowheretown
    zipcode: 12345

其中连续的项目通过-来表示，map 结构的key/value结构使用:来分隔。要求同一级别的数据前面缩进的空格数要相同。在上面的例子中，Simone可使用hourse.family.children[3]来引用。

其他的相关内容：

  • 要添加注释，使用#符号。
  • 布尔值使用true和false
  • 空值使用null或者~
  • 数值支持
    • 整数，如12
    • 八进制数，如012
    • 16进制数，如0xC
    • 浮点数，如1.24
    • 指数，如1.2e3
    • 无穷: .inf

结束前，我们看这样一个例子：

title:
 - type: main
   text: My Book
 - type: subtitle
   text: An investigation of metadata

在这个例子中，要访问My Book,应该使用title[1].text。这里的两个-表示title下是一个数组结构。

  1. 这是在表格单元格中添加换行的唯一形式。↩

  2. 在本博客中，斜体的display被设置成了block并且居中对齐，主要用于图、表的标题。↩

  3. 未理解。↩