本文基本翻译自 Kramdown官方网站提供的语法文档

有关语法细节本文并没有过多涉及，本文侧重于通过实例展示 Kramdown 使用时较为 tricky 的点。有的地方可能直观显示并不明显，但在 HTML 标签中区别很大，所以建议本文结合 F12 食用。

• 结构元素
  • 空行
  • 段落
  • 标题
    • 用法
    • 标题ID
  • 引用块
  • 代码块
    • 用法
    • 代码语言
  • 表单
    • 有序和无序表单
    • 定义表单
  • 表格
    • 表格中每行的元素
    • 分割线
    • 表格中文字的对齐方式
  • 水平分割线
  • 数学公式
  • HTML块

结构元素

空行

只包含空格的行会被认定为空行，多个连续的空行只被显示为一行。

段落

一行或多行连续的文字会被认定为段落。多个段落可以用一个空行来分开。注意源文件段落中的断行不代表输出中的断行，如果想实现段落中强制断行的效果，需要在行末加两个以上的空格或一个\\。

• 代码：

这是一个连续的段落，我们可以注意到虽然源代码在这
里有一个断行，但是并不会被显示出来。

这是另外一段，在这里我们想手动断行，于是我们在这\\
加入了两个反斜杠。

• 显示：

这是一个连续的段落，我们可以注意到虽然源代码在这 里有一个断行，但是并不会被显示出来。
这是另外一段，在这里我们想手动断行，于是我们在这
加入了两个反斜杠。

标题

用法

在每个区块前，我们可以用#符号来标记标题。#的数量表示此为几级标题，最多支持六级。可以在标题的末尾用任意数量的#结束。

标题ID

Kramdown 支持为每个标题指定 HTML 标签中的 ID 属性。在标题后加入{#id}代码即可。如果开启了 auto_ids=true，则 Kramdown 会自动为每个标题添加 ID。

• 代码：

#### 这是一个四级标题  {#level4}

###### 这是一个六级标题    ###### {#level6}

##### 这是一个五级标题，注意结尾的#数量 ### {#level5}

• 显示：

这是一个四级标题

这是一个六级标题

这是一个五级标题，注意结尾的#数量

引用块

如果想把一段文字用引用块包裹起来，只需要在文字前加上>符号即可，每行中的多个>会被识别为多级引用。

• 代码：

> 这是一段引用。
> 
> > 多级引用。
> 
> 引用结束

• 显示：

这是一段引用。

多级引用。

引用结束

代码块

用法

Kramdown 既支持传统 Markdown 语法中四个空格或一个tab开启代码块的方法，也可以使用~~~来封闭代码块区域。

代码语言

Kramdown 支持在代码块后标注代码语言。用法类似为标题增加 ID，即在代码块后用{: .language}表示。如果代码块采用~~~封闭的形式，除了上述方法外还可以在代码块的首行直接声明语言。

• 代码：

以下是两段代码：

    cout<<"helloworld";
{: .language-cpp}

~~~  javascript
console.log('Helloworld!');
~~~

• 显示：

以下是两段代码：

cout<<"helloworld";

console.log('Helloworld!');

表单

有序和无序表单

表单分为有序和无序两种，段落使用空格或tab分隔开文字和表单标记。无序标记可以使用*+-，有序标记直接用数字加点即可。注意，有序和无序表单不能混用。

• 代码：

1. 这是第一项
2. 这是第二项
* 这是无序表单
+ 注意有序和无序不能混用
- 这是无序表单
3. 这是第三项

• 显示：

1. 这是第一项
2. 这是第二项
   • 这是无序表单
   • 注意有序和无序不能混用
   • 这是无序表单
3. 这是第三项

定义表单

定义表单是 Markdown 中没有的特性，作用是在一个属于后增加一行或几行定义。定义表单中的每行开头需用:标记。

如果:前面没有空行的话，即使定义中包含区块，这一行定义也会在 HTML 中直接作为文字输出；相反之前有空行的定义在 HTML 输出为<p>段落。

• 代码：

Kramdown
: 用 Ruby 实现的 Markdown 的解析器
:    当前网页即用 kramdown 解析生成

空行的区别
: 这里没有空行，故直接输出为 text
 > 即使这里有一个引用块

: 这里有空行，输出文字会被包裹进段落。

• 显示：

Kramdown

用 Ruby 实现的 Markdown 的解析器

当前网页即用 kramdown 解析生成

空行的区别

这里没有空行，故直接输出为 text

即使这里有一个引用块

这里有空行，输出文字会被包裹进段落。

表格

在 Kramdown 中，表格通常用|标记。描述表格可能需要用到以下几种标记方法

表格中每行的元素

表格是按行进行书写的。如果想开启一个表格，那么第一行文字中需要存在至少一个没有被认作为其他表格标记的|标记。之后的每行中，不同单元格用|分开，结尾的|可加可不加。每个单元格中只能有一行文字。

• 代码：

| First cell|Second cell|Third cell
| First | Second | Third |

First | Second | | Fourth |

• 显示：

分割线

分割线的主要作用是将表格划分成多个不同的区域，即不同的<tbody>标签下。

分割线标记需满足以下两个条件

• 只包含|-+:,空格和tab；

• 至少包含一个-和一个|。

要注意在同一个分割线中，|-+三种符号是等价的，并没有实质含义。

每个表格中的第一个分割线会被认定为表头分割线，在它上面的所有行会被输出为表格的标题。

如果把分割线中的-替换为=，那么这个分割线会被认定为表尾分割线，在它下面所有的行都会被输出为表格的表尾。只有最后一个表尾分割线会被识别，之前的多余表尾分割线及之后所有的普通分割线都会被自动忽略。

所有分割线都是可加可不加的。

• 代码：

| First cell|Second cell|Third cell
|-
1|2|3|
4|5|6
7|8|9
-|
由于|这里有|分割线
所以|属于不同|的区域
=|
这里|是|表尾
+-|------| ---|
注意|表尾后|的分割线
-|-
都|不起|作用

• 显示：

表格中文字的对齐方式

在表格中，使用分割线内的:来对单元格中的文字进行对齐。:-代表左对齐，:-:代表居中对齐，-:代表右对齐；如果不设置的话，单元格采用默认对齐。

如果不需要声明对齐方式，则所有分割线都是可以省略不写的，且分割线内也无需按表格数量一一对应分隔符数量；但是如果想要明确对齐方式，则以上两点的情况均相反。声明在表头分割线中的对齐方式对表中后续整列单元格均有效。

• 代码：

| 左对齐|居中对齐|右对齐
:-|:-:|-:
1|2|3|
4|5|6
+-|-+-|+:-
7|8|9|

• 显示：

水平分割线

Kramdown 支持用三个及以上的*-_符号表示文章中的水平分割线。注意这三种符号之间彼此不能混用。

• 代码：

分割线样式1

***
分割线样式2

---
分割线样式3

___

• 显示：

分割线样式 1

分割线样式 2

分割线样式 3

数学公式

Kramdown 支持 LaTeX 的句中或独立数学公式，用法与 LaTeX 基本类似，以$$标记起始和结束，$$可以与公式写在同一行，也可以写在单独一行。公式的内容要用\backslash begin{displaymath}...\end{displaymath}语句或者其他特定的\begin语句包裹。

• 代码：

$$
\begin{align*}
  & \phi(x,y) = \phi \left(\sum_{i=1}^n x_ie_i, \sum_{j=1}^n y_je_j \right)
  = \sum_{i=1}^n \sum_{j=1}^n x_i y_j \phi(e_i, e_j) = \\
  & (x_1, \ldots, x_n) \left( \begin{array}{ccc}
      \phi(e_1, e_1) & \cdots & \phi(e_1, e_n) \\
      \vdots & \ddots & \vdots \\
      \phi(e_n, e_1) & \cdots & \phi(e_n, e_n)
    \end{array} \right)
  \left( \begin{array}{c}
      y_1 \\
      \vdots \\
      y_n
    \end{array} \right)
\end{align*}
$$

• 显示：

这里是带 blackslash 的$$ \LaTeX $$公式

这里是的$\LaTeX$公式

HTML块