markdown语法及pandoc扩展

pandoc 扩展：标题前空行 blank_before_header

pandoc中，需要在标题的上一行留出一个空白行。因为普通行文中，被#号顶头的可能性很大，强制要求前面留出一个空行，行文时出现#号开头的行就没什么问题了。

pandoc 扩展：标题属性 header_attributes

标题行后面可以使用这样的语法来添加标题属性，这个属性通常为HTML和Latex使用。其语法为

# 标题{#id .class .class key=value key=value}

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

pandoc扩展：自动生成ID auto_identifiers

在没有指定标题id的情况下，pandoc会自动为每个标题生成一个id，生成id的方法是

• 移除所有格式，链接等。
• 移除所有标点符号（下划线，减号除外）
• 用减号替代所有的空格
• 將所有英文字母转为小写
• 移除第一个字符前的所有内容（ID 不能以数字或标点符号开头）。
• 如果剩下为空串，则使用section作为ID

由以上的规则知，如果标题为中文的情况下，基本上就什么都不剩啦。所以在使用pandoc的时候，通常要把这个扩展关掉。

如果指定了--section-divs选项，那么在生成的文档中，每个小节都会用div包住，并用该标题的id作为这个div的id。这样做的好处是，可以使用javascipt来对整个小节进行操作。

pandoc扩展：默认标题引用 implicit_header_references

todo

无序列表

这是代码：

* item 1
* item 2
* item 3

效果如下：

• item 1
• item 2
• item 3

这里的*可以替换成+和-，效果一样。各个列表项之间可以加入空行。

有序列表

1. item 1
1. item 2
1. item 3

效果如下：

1. item 1
2. item 2
3. item 3

注意这里和无序列表的区别，前面的*号换成数字，这里数字的具体值并不重要，全部写成1就可以了，编译器会自动给它们编号的。

嵌套列表

无需和有序列表、无序列表之间以及有序列表之间都可以嵌套，如下述代码

* item 1
    1. sub item 1
    1. sub item 2
    1. sub item 3
* item 2
* item 3

效果如下：

• item 1
  1. sub item 1
  2. sub item 2
  3. sub item 3
• item 2
• item 3

注意这里的嵌套列表，需要缩进四个空格

多段列表

有时候，每个列表项都需要几段话来说明，这这种情况下，后面的段落需要有四个空格的缩进，段内需要换行时使用两个空格，如下所示

1. 这是item1 ， 假设我们有很长的很长的很长的很长的  
    很长的很长的很长的很长的很长的很长的很长的说明    这是说明的第二段，很长的很长的很长的很长的很长的  
    很长的很长的很长的很长的很长的很长的说明    这是说明的第三段，很长的很长的很长的很长的很长的  
    很长的很长的很长的很长的很长的很长的说明2. 这是项目2，它的说明不怎么长

效果如下：

1. 这是item1 ， 假设我们有很长的很长的很长的很长的
   很长的很长的很长的很长的很长的很长的很长的说明

   这是说明的第二段，很长的很长的很长的很长的很长的
   很长的很长的很长的很长的很长的很长的说明

   这是说明的第三段，很长的很长的很长的很长的很长的
   很长的很长的很长的很长的很长的很长的说明

2. 这是项目2，它的说明不怎么长

行内链接

代码：

[猎数博客](http://www.bagualu.net/wordpress)

效果如下：

猎数博客

链接的url后面可以跟title，格式为[文字](url title)，url和title之间有一个空格，title需要用引号或者小括号包起来 如下所示：

代码：

[猎数博客](http://www.bagualu.net/wordpress "关注科技，数据挖掘")

效果：

猎数博客

参考链接

在参考链接中，链接和内容可以分开，这样有多个同样的链接时，只需要写一次，如下所示，其中链接的内容可以单独写在文章的下面。

- [文章1][1]
- [文章2][2]
- [文章1][1][1]: http://www.bagualu.net/wordpress/archives/5284
[2]: http://www.bagualu.net/wordpress/archives/5336

这段代码产生的效果如下：

• 文章1
• 文章2
• 文章1

其中第二个括号的数字可以为文字，这是用作区别各个参考链接的标识。比如[文章1][artical1] , 第二个括号中的标签不区分大小写。

如果第二个放括号为空或者没有第二个方括号，也可以做一个参考链接，此时，第一个中括号的内容就时标签内容，如[my web] , 在后面的参考链接部分只要写上[my web]: http://xxx.com就可以了。这是一个隐式的参考链接。

自动链接

在不指定链接文字的情况下，可以用这个语法直接生成一个链接

<http://www.bagualu.net/wordpress>

生成的链接效果为：

http://www.bagualu.net/wordpress

pandoc定义扩展definition_lists

可以用下面的方式来给出一个定义

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

这段代码产生的效果如下：

词语1

词语1的定义

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

词语2

词语2的定义

其中词语所在行必须独占一行。词语后面的空行是可选的。

定义部分以:或者~开头，前面可以有一个或者两个空格。

一个词语可以有多个定义。每个定义可以有一个或多个块，其中可以包含代码，列表等。注意这里的每个块必须有四个空格的缩进（包括第一个块，四个空格从:或者～开始计算，不包括这两个标点符号前面的空格，也就是这两个符号之后要有四个空格，然后才是定义的内容），不然不会被认为是一个有效的定义列表。

pandoc实例扩展example_lists

实例扩展使用@开始，如下所示

(@)  第一个实例，编号为1。
(@good)  第二个实例，编号为2。
关于上面这个实例的更多解释
(@)  第三个实例，编号为3。可以像这样引用前面定义的实例，如请参考(@good)

生成的效果如下：

1. 第一个实例，编号为1。
2. 第二个实例，编号为2。 关于上面这个实例的更多解释
3. 第三个实例，编号为3。

可以像这样引用前面定义的实例，如请参考(2)

缩进代码块

一个以四个空格字符开头的段落被认为是代码，其中的字符不会被特殊处理，而是会被原样输出。注意其中的空行不需要使用四个空格。

行内代码

行内的代码使用`。 如`printf("hello world")`。

pandoc扩展： 栅栏代码块 fenced_code_blocks

大段的代码可使用```或者~~~包起来, 如

```c
int main(){return 0;
}
```

如果在代码中使用到了``` ，可以在开头栅栏中使用更多的`, 比如四个，然后在结束的地方使用同样多的`就可以了。

pandoc 扩展： 行块 line_blocks

行块是以|开头的连续行，注意这里|后面的空格。行与行间的距离在输出时会原样保留，每行前的空白也会保留。如下所示

| 你好，第一行
|   你好，这是第二行
|       第三行

你好，第一行
  你好，这是第二行
      第三行

这种语法有效的保留了行前的空格，在有些情况下可以对格式有很好的控制。

pandoc表名扩展table_captions

这个扩展可以在表前或者表后使用一个独立的段来给出表格的名字，该段以Table:或者:开头。如后面所示

简单表格扩展simple_tables

简单表格的代码是这样的:

   右对齐   左对齐     中间对齐     缺省
--------    -------  ----------- --------
       1     2          2           33         2         3           3Table: 简单的表格

这个代码产生的表格为：

表格的对齐方式为，表头与第二行虚线之间的对齐关系。表格下面必须有一个空白行。其中表头可以省略，此时必须在表格结束的地方添加一行虚线。如下所示

--------    -------  ----------- --------
       1     2          2           33         2         3           3
--------    -------  ----------- --------Table: 简单的表格

多行表格扩展multiline_tabes

和上面的简单表格一样，多行表格只是让每个单元格或表头可以跨越多行。而表格的每行之间要有一个空行，另外，表头和表尾的虚线行不能省，如下所示

---------------------------------------------header    heander      多行的  
     1          2          内容
----------  ----------   --------------------单元格1    单元格2       多行的  
                            单元格单元格3    单元格4       单元格5
----------------------------------------------: 多行的表格

其产生的表格如下：

管道表格扩展pipe_tabes

管道表格可显示的指定各列的对齐方式，但是管道表格的单元格不可以是多行的，不能包含块级元素。下面是一个例子

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |
: 管道表格，对齐方式通过上面虚线中的`:`指定

它产生的表格如下：

emacs风格的表格

在emacs中，可以通过M-x table-insert来插入一个文本的表格，其基本格式如下

+-----+-----+-----+
|c1   |  c2 |  c3 |
+-----+-----+-----+
|d1   | d2  | d3  |
+-----+-----+-----+
| e1  |e2   |  e3 |
+-----+-----+-----+

其显示出的效果如下：

如果你喜欢使用emacs，那么插入这样的表格还是很方便的。

pandoc标题块扩展 pandoc_title_block

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

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

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

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

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

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

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

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

pandoc YAML元数据扩展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 Oneaffiliation: University of Somewhere
- name: Author Twoaffiliation: 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$

段级html代码嵌入及pandoc扩展markdown_in_html_blocks

嵌入的html代码段必须在头上和结尾出与markdown的其他部分用一个空行分开，并且起始tag和结束tag行前不要有空格或者tab。其次，在标准的markdown语法中，html代码段中间的markdown语法不会被处理。比如你用html代码段插入一个表格

<table>
<tr><td>[博客](http://www.bagualu.net)</td><td>**col2**</td></tr>
</table>

其中的链接和**不会被标准的markdown处理。而在pandoc中有一个扩展叫markdown_in_html_blocks ， 打开这个扩展，可以使html代码块中markdown被解析。在pandoc中，上面的代码会生成链接和强调。

由此可见html代码段中间的markdown语法已经被处理。

行级的html代码嵌入

除了在段级的html代码，在行级嵌入html代码，可以直接使用标签就可以了。行级标签下的markdown语法会被处理。

pandoc扩展raw_html

严格说这不算是一个扩展，因为标准markdown中就有这个支持，这里做成一个扩展是为了可以方便的关掉它。对于嵌入的html格式，当输出为latex时，其中的html代码会被直接丢掉。由此可见，要在markdown中插入表格是一个比较麻烦的事情，因为不同格式下，其代码是不一样的。