Markdown 有序列表和无序列表的写法与规则

Markdown 写作约 7 分钟

Markdown 有序列表就是每行以数字、句点和空格开头,比如 1. 第一项,无序列表则以 -、* 或 + 加空格开头。有序列表只有第一个数字起作用,后面由渲染器自己往上数,所以每行都写 1. 也会显示成 1、2、3。换了标记字符,或者在 . 和 ) 之间切换,都会另起一个新列表。条目之间只要有一个空行,列表就变成松散列表,每一项会被包上段落,间距也随之变大。

无序列表

- 买牛奶
- 买面包
- 买鸡蛋

CommonMark 规范规定无序列表标记是 -、+ 或 *,三种渲染出来是同一种列表。标记后面至少要跟一个空格或制表符,所以 -一项 只是普通文字。标记前面最多可以缩进三个空格,缩进到四个空格就成了缩进代码,或者在紧跟段落、列表项时变成续行。

标记字符本身决定了它是不是同一个列表。规范说只有字符相同才算同一类标记,所以下面是两个列表,不是一个:

- foo
- bar
+ baz

输出是一个包含 foo 和 bar 的 <ul>,再加一个只含 baz 的 <ul>。从别处粘贴列表时标记中途变了,或者想故意把长列表断开,都会碰到这条规则,平时一个列表就固定用一种标记。有序列表也一样,. 和 ) 算两种不同的类型。

有序列表

1. 预热烤箱
2. 和面
3. 烤 20 分钟

有序列表标记是一到九位数字后面跟 . 或 ),两种分隔符在 CommonMark 里都合法,不过 GitHub 文档里的例子用的是句点。限制九位数字是因为更长的数字在某些浏览器里会整数溢出,所以 1234567890. 文字 只是一个普通段落。

只有第一个数字算数

规范说有序列表的起始数字由第一项决定,后面各项的数字会被忽略。下面三个列表生成的 HTML 一样:

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

三个都显示成 1、2、3。如果第一项写成 5.,HTML 里会带上 <ol start="5">,列表从 5 数到 7。0 也可以当起始数字,0. 从零开始,前导零也行,003. 从 3 开始,负数则不是标记。

所以很多人干脆每行都写 1.,挪动或插入条目都不用重新编号,diff 里也只有改动的那一行。代价是源码读起来差一些,不渲染 Markdown 的地方,比如纯文本邮件,会看到一列 1。顺序编号读源文件更舒服,全写 1 更好维护。

打断段落的列表必须从 1 开始

CommonMark 允许列表前面不留空行,Foo 后面直接跟 - bar,就是一个段落加一个列表。有序列表多了一道保险,只有从 1 开始的列表才能打断段落,为的是不把手动折行的文字误认成列表,比如下面这段

The number of windows in my house is
14.  The number of doors is 6.

以 14. 开头的那一行仍然属于上面的段落。规范也承认还有漏网的情况,折行后碰巧以 1. 开头的话,照样会变成列表。如果一个从别的数字开始的有序列表紧跟在段落后面,结果显示成了文字,在它前面加一个空行就行,空行之后这条限制不再适用。

紧凑列表和松散列表

条目之间没有空行是紧凑列表,任意两项之间有空行,或者某一项直接包含两个中间隔着空行的块,就是松散列表。HTML 上的区别是松散列表会把条目文字包进 <p>,紧凑列表不会。

- a
- b

- c

这是一个松散列表,不是中间留了缝的紧凑列表。任意两项之间的一个空行会让每一项都变成段落,因为松散是整个列表的属性。间距比预想的大时,通常删掉多余的空行,或者在所有条目之间都加上空行。

按规范的例子,条目里围栏代码块内部或引用内部的空行不会让列表变松散。

条目里的段落和代码

只要后面的行缩进到条目文字起始的那一列,条目就会继续。这一列等于标记的宽度加上标记后面的空格:

- 第一项

  同一项的第二段。

1. 第一步

   第一步的说明。

   ```bash
   make build
   ```

2. 第二步

- 下面内容列是 2,1. 下面是 3,10. 下面是 4。缩进不够就会离开列表自成一段,规范的例子是 - one 后面空一行,再跟一行只缩进一个空格的 two。段落多缩进几格没关系,但多出四个空格就变成代码。整项往里缩进是嵌套,规则在引用和嵌套列表里单独讲。

围栏代码块遵守同样的缩进规则,围栏和内容都要缩进到内容列。围栏本身的写法见 Markdown 代码块。要在条目里放缩进代码块,就在内容列之外再缩进四个空格,也就是 - 下面六个空格。

在列表后面接代码块

反过来的问题是列表后面跟着一段不属于它的代码。列表后空一行再写缩进代码块,规范会把这些缩进行读成最后一项的又一段。规范给的办法是在中间插一条 HTML 注释:

- foo
- bar

<!-- -->

    code

注释本身不渲染任何内容,却能结束列表,后面的缩进块就是真正的代码。同样的办法也能把两个同类型的列表隔开。从第 0 列开始的围栏代码块也会结束列表,因为它缩进不够,不属于最后一项,拿不准的时候直接用围栏。

妙言里的列表

妙言的预览用 cmark-gfm 渲染,所以上面的规则就是你看到的结果。编辑器在 V4.9.0 的源码里加了回车续写列表:

  • 光标在以 -、* 或 + 开头的行尾,回车会用同一个标记开下一行。
  • 在 1. 或 10. 这样的有序行上,回车会用数字加一开下一行,1. a 后面是 2.,10. item 后面是 11.。它按顺序计数,不会照抄一列 1。只识别句点形式,1) 开头的行不会续写。
  • 在只剩标记的空条目上回车,会删掉标记留下一个空行,列表到此结束。
  • 光标在行中间回车,或者按 Shift-回车,只换行,不加标记。

同样的续写也适用于任务列表的 - [ ],新行的方框会重置为未完成,见 Markdown 任务列表。

常见问题

Markdown 列表的数字必须写对吗?

不用。只有第一个数字起作用,后面的由渲染器数。每行都写 1. 是合法的,也很常见。

有序列表能从 1 以外的数字开始吗?

可以,第一项写成 5.,列表就从 5 开始往下数。如果它紧跟在段落后面没有空行,不会渲染成列表,所以前面留一个空行。

为什么我的列表断成了两个?

标记变了。- 和 + 是不同的列表类型,1. 和 1) 也是。一个列表只用一种标记。

为什么列表项之间多出了空白?

条目之间某处有空行,列表变松散了。删掉空行,或者在所有条目之间都加。

怎么在列表项里放代码块?

把围栏缩进到条目的内容列,- 下面两个空格,1. 下面三个空格。