嘿，我是 Agnes。今天咱们不聊那些晦涩难懂的技术文档，就来聊聊 Markdown 里最基础、却也是最容易让人踩坑的“列表”。
很多新手刚接触 Markdown 时，总觉得：“写个列表能有多难？不就是加个横线或者数字吗？” 结果一提交，发现格式乱了、缩进没了、甚至变成了普通的文本。别慌，这篇指南就是为你准备的。我会把无序列表、有序列表、嵌套列表，以及那些让人头大的避坑指南，一次性给你讲透。
为什么列表这么重要？
想象一下，你正在看一篇技术博客或者一份产品需求文档，满屏都是密密麻麻的文字，没有任何层次感。是不是只想关掉页面？
列表的作用，就是把杂乱的信息“梳理”得井井有条。它能帮助读者快速抓取重点，也能让你的思路在写作时更加清晰。无论是 GitHub 上的 README，还是语雀、Notion 里的笔记，列表都是必不可少的“排版神器”。
一、无序列表：轻松自在的“小圆点”
无序列表，顾名思义，就是没有顺序之分的列表。它们通常用项目符号（比如小圆点、圆圈等）来表示。在 Markdown 中，创建无序列表非常简单，只需要在行首加上 -、+ 或 * 即可。
1.1 基本用法
这三种符号在绝大多数 Markdown 渲染器中效果是一样的，都会显示为小圆点。你可以任选一种，但我个人更推荐用 -，因为它在键盘上最容易找到，而且视觉上更清爽。
- 苹果
- 香蕉
- 橙子
渲染后的效果大概是这样的：
- 苹果
- 香蕉
- 橙子
1.2 不同符号的效果
虽然效果一样，但为了让你理解为什么三种都可以，我们可以简单看看它们的兼容性。有些古老的论坛系统可能只支持特定的符号，但在现代的编辑器（如 Typora、VS Code、Obsidian）中，三者通用。
+ 第一项
+ 第二项
+ 第三项
* 第一项
* 第二项
* 第三项
二、有序列表：井井有条的“数字键”
有序列表用于表达有先后顺序或优先级顺序的内容。在 Markdown 中，使用数字加上英文句号 . 来创建。
2.1 基本用法
注意，这里的数字并不完全决定渲染后的显示顺序。Markdown 的规则是：列表项前的数字决定了它是有序列表的一部分，但渲染时通常会按照你输入的数字顺序显示，或者自动从 1 开始递增。
1. 早起
2. 锻炼
3. 吃早餐
渲染效果：
- 早起
- 锻炼
- 吃早餐
2.2 一个有趣的细节
你可能会发现，有时候你输入的数字不是连续的，比如：
3. 第三件事
1. 第一件事
5. 第五件事
渲染后的效果通常会变成：
- 第三件事
- 第一件事
- 第五件事
或者某些渲染器会保留你输入的数字。为了避免混淆，建议始终从 1 开始，并且连续递增。这样既符合阅读习惯，也能确保在不同平台上的表现一致。
三、嵌套列表：让结构更清晰
这是新手最容易出错的地方，也是最能体现 Markdown 强大之处的地方。嵌套列表可以让你在列表项中再创建子列表，从而形成清晰的层级结构。
3.1 如何缩进
嵌套的关键在于缩进。通常，使用两个或四个空格（或者一个 Tab 键）来缩进子列表。
- 水果
- 苹果
- 香蕉
- 蔬菜
- 白菜
- 萝卜
渲染效果：
- 水果
- 苹果
- 香蕉
- 蔬菜
- 白菜
- 萝卜
3.2 混合嵌套
你还可以在无序列表中嵌套有序列表，或者反过来。
1. 准备阶段
1. 确定目标
2. 收集资料
2. 执行阶段
- 行动一
- 行动二
3. 总结阶段
1. 回顾成果
2. 规划下一步
渲染效果：
- 准备阶段
- 确定目标
- 收集资料
- 执行阶段
- 行动一
- 行动二
- 总结阶段
- 回顾成果
- 规划下一步
四、一键生成：懒人必备技巧
如果你不想手动输入，或者需要快速生成一个复杂的列表结构，这里有一些小技巧。
4.1 使用工具生成
现在很多在线工具都支持 Markdown 生成器。比如，你可以输入你想要的结构，工具会自动帮你生成对应的 Markdown 代码。
4.2 代码片段快速插入
如果你常用 VS Code，可以安装一些插件，如“Markdown All in One”，它提供了快捷键来快速插入列表。
五、避坑指南：这些错误你一定不想犯
5.1 缩进不一致
这是最常见的问题。如果你在嵌套列表时，缩进用的空格数不一致，可能会导致渲染错误。
错误示例：
- 水果
- 苹果
- 蔬菜
- 白菜
正确做法： 保持缩进一致，建议使用两个或四个空格。
5.2 数字后没有句号
有序列表必须使用数字后跟英文句号 .，而不是中文句号 。 或逗号 ,。
错误示例：
1、第一项
2. 第二项
正确做法：
1. 第一项
2. 第二项
5.3 列表项中间有空行
在某些渲染器中，列表项中间如果有空行，可能会导致列表中断。
错误示例：
- 第一项
- 第二项
正确做法： 尽量保持列表项连续，如果需要分段，可以使用段落而非空行。
5.4 使用中文标点
确保所有符号都是英文半角符号，包括句号、逗号、括号等。
六、实际应用场景
6.1 写技术文档
在写 API 文档时，用列表来描述参数。
### 参数说明
- `name` (string): 用户名，必填
- `age` (number): 年龄，可选
- `email` (string): 邮箱，必填
6.2 做读书笔记
用嵌套列表来整理书籍的结构。
## 《高效能人士的七个习惯》
1. 习惯一：主动积极
- 定义：不抱怨环境，主动承担责任
- 实践方法：每天列待办事项
2. 习惯二：以终为始
- 定义：明确人生目标
- 实践方法：撰写个人使命宣言
6.3 整理购物清单
用无序列表来记录需要购买的东西。
## 购物清单
- 牛奶
- 鸡蛋
- 面包
- 蔬菜
- 白菜
- 西红柿
七、小结
列表是 Markdown 中最基础也最实用的功能之一。掌握无序列表、有序列表和嵌套列表的用法，能让你的文档更加清晰易读。记住几个关键点：符号选一种、缩进要一致、数字后加句号、标点用英文。
希望这篇指南能帮助你更好地使用 Markdown 列表。如果有任何问题，欢迎随时交流！