Markdown 列表语法完全指南

Markdown 列表是什么

写文档的时候，列表是最常用的排版方式之一——不管是列要点、排步骤，还是做待办清单，都离不开它。Markdown 提供了几种列表类型：无序列表（bullet list）、有序列表（numbered list）、嵌套列表（nested list）和任务列表（task list）。

这篇教程会从最基础的写法讲起，到嵌套规则、缩进陷阱，再到不同平台的兼容性差异，争取让你看完这篇就够用了。

无序列表（Unordered List / Bullet List）

无序列表就是每一项前面带个圆点的列表，也有人叫它"项目符号列表"或"bullet points"。

语法很简单，在行首写 -、* 或 +，加一个空格，再写内容就行：

- 苹果
- 香蕉
- 橘子

渲染效果：

• 苹果
• 香蕉
• 橘子

三种符号你可以任选一种，效果完全一样：

* 用星号也行
+ 用加号也可以
- 用减号当然没问题

不过建议同一篇文档里只用一种。说实话这是个人习惯问题，但混着用看着确实有点乱，而且部分解析器会把不同符号开头的项目识别成不同的列表块，中间自动插入间距。我自己的习惯是全部用 -，因为它和其他 Markdown 语法冲突最少（* 可能和加粗斜体混淆）。

有序列表（Ordered List / Numbered List）

有序列表的每一项前面是数字，适合写步骤、排名这类有顺序要求的内容：

1. 打开编辑器
2. 新建文件
3. 开始写作

渲染效果：

1. 打开编辑器
2. 新建文件
3. 开始写作

这里有个很多人不知道的细节：数字其实不影响最终的编号顺序。Markdown 解析器会按照列表项出现的顺序自动编号。所以下面这样写，渲染结果跟上面完全一样：

1. 打开编辑器
1. 新建文件
1. 开始写作

但有个例外——起始数字是有意义的。如果你从 3 开始写，列表会从 3 开始编号：

3. 第三步
4. 第四步
5. 第五步

这个行为是 CommonMark 规范明确定义的，GitHub、Obsidian、VS Code 等主流平台都遵循这个规则。

一个实用建议：如果你以后可能会在中间插入或删除某一项，全部用 1. 来写会方便很多——改一处不用把后面所有数字都重新排一遍。

对了，有序列表的标记符必须用句号 .，不能用括号 )。像 1) 这种写法在部分解析器里不被支持，尽量别用。

嵌套列表（Nested List / Sublist）

嵌套列表就是列表里面再套一层列表，用来表达层级关系。写法是通过缩进来表示层级。

缩进规则

缩进可以用空格或 Tab，关键点是：

• 空格缩进 2-4 个都可以被识别
• Tab 缩进 1 个等于 4 个空格
• 子列表的标记符必须比父列表的内容多缩进至少 1 个空格

- 水果
  - 苹果
    - 红富士
    - 青苹果
  - 香蕉
- 蔬菜
  - 白菜
  - 萝卜

渲染效果：

• 水果
  • 苹果
  • 红富士
  • 青苹果
  • 香蕉
• 蔬菜
  • 白菜
  • 萝卜

2 空格 vs 4 空格

这里有坑。CommonMark 规范对无序列表的定义是：缩进 1-3 个空格都算子列表。但不同平台的行为不完全一致：

我自己实测下来，2 空格在绝大多数平台上都能正常工作，而且看起来更紧凑，也是 GitHub 官方文档推荐的做法。之前有段时间我习惯用 4 空格，后来在一个项目里跟别人协作时发现他们全用 2 空格，混在一起特别难看，就统一改成 2 了。

顺便提一句，如果你在列表里缩进超过 4 个空格（相对于列表标记符），有的解析器会把它当成代码块来处理——这也就是为什么嵌套太深的时候，文字突然变成了等宽字体的代码。Reddit 上就有人吐槽过这个问题。

有序 + 无序混合嵌套

有序列表和无序列表可以互相嵌套，比如：

1. 准备食材
   - 面粉 500g
   - 鸡蛋 3 个
   - 牛奶 250ml
2. 开始制作
   1. 把面粉倒入盆中
   2. 打入鸡蛋
   3. 倒入牛奶搅拌均匀
3. 烘烤

这种混合嵌套在写操作步骤或技术文档时特别好用。

任务列表（Task List / Checklist）

任务列表也有人叫"待办清单"或"checkbox list"，是 GitHub Flavored Markdown（GFM）的扩展语法。在普通列表的基础上加上 [ ] 或 [x] 就行：

- [x] 完成需求文档
- [x] 评审代码
- [ ] 部署测试环境
- [ ] 上线发布

渲染效果：

• [x] 完成需求文档
• [x] 评审代码
• [ ] 部署测试环境
• [ ] 上线发布

注意几点：

• [ ] 里面是一个空格，表示未完成
• [x] 里面是小写字母 x，表示已完成（大写 X 大多数平台也支持）
• 方括号前面是 -，和普通列表的标记符一样

任务列表在 GitHub 的 Issues 和 PR 中特别常见——你可以在 Markdown 里直接勾选和取消勾选，GitHub 会自动更新源文件。Obsidian 和部分编辑器也支持这个交互。

不过要注意，任务列表属于 GFM 扩展语法，不是所有 Markdown 解析器都支持。原始的 Markdown 规范里没有这个东西，在一些老旧的渲染器上可能显示为普通文本。

列表中嵌入其他元素

这个功能很多人不知道，但确实很实用。你可以在列表项之间插入段落、代码块、引用甚至图片——只要缩进对了就行。

列表中加段落

在列表项下面空一行，然后缩进对齐到文字内容的位置：

- 第一点

  这是第一点的补充说明，缩进到和"第"字对齐的位置。

- 第二点

列表中加代码块

在列表里嵌入代码块需要缩进 4 个空格（相对于标记符）或 1 个 Tab，加上围栏标记：

1. 安装依赖：

   ```bash
   npm install markdown-it

2. 引入模块

列表中加引用

- 一个重要的事实

  > 这段引用和上面的文字属于同一个列表项

- 另一个要点

说实话，这种嵌套写法在实际用的时候很容易把缩进搞乱。我的建议是：如果嵌套超过两层，考虑用标题来分割内容，别硬塞在列表里。

常见问题与踩坑经验

列表之间被意外合并

如果你写了两个列表，中间没有其他内容，有些解析器会把它们合并成一个。解决办法是在两个列表之间加一行不是列表的内容（比如一行普通文字或 <!-- --> 注释）：

- 列表 A 第一项
- 列表 A 第二项

<!-- -->

- 列表 B 第一项
- 列表 B 第二项

有序列表不想从 1 开始

前面说过起始数字是有意义的，但你想从特定数字开始时，直接写那个数字就行。不过要注意，不是所有渲染器都支持非 1 起始——有些会忽略起始数字直接从 1 开始。

嵌套太深变成代码块

这是我之前踩过的坑。在写一个多层级的大纲时，嵌套到第四层发现文字突然变成了等宽字体。原因就是缩进超过了 4 个空格（相对于最外层标记符），解析器把它当成了缩进式代码块。解决办法是减少嵌套层级，或者用 HTML 的 <ul> / <ol> 标签来处理深层嵌套。

字母列表或罗马数字列表

标准 Markdown 不支持 a. b. c. 或 i. ii. iii. 这种格式的有序列表。如果你需要的话，有几个方案：

• 用 HTML：<ol type="a"> 可以生成字母列表
• 用 Pandoc：它支持 fancy_lists 扩展，可以用 a.、A.、i.、I. 等标记符
• 在 GitHub 和大多数平台上，目前只能用纯数字

列表类型速查表

不同平台兼容性对比

参考来源

1. CommonMark Spec - Lists — CommonMark 官方列表教程
2. Markdown Guide - Basic Syntax — Markdown Guide 列表语法参考
3. GitHub Docs - Lists — GitHub 官方列表语法文档
4. jmmv.dev - Markdown Lists — Markdown 列表格式化最佳实践
5. Markdown Guide - Task Lists — Markdown Guide 任务列表扩展语法