Markdown 有序列表和无序列表的写法与规则
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. 下面三个空格。
