Markdown: Markdown 列表语法与嵌套
列表是把零散信息组织成结构化内容的最简单方式——读者扫一眼就能抓住要点。
1. 你将学到
- 无序列表和有序列表的语法
- 列表嵌套的正确写法
- 任务列表的创建与使用
- 列表中的段落、代码块和引用
- 常见列表错误及修正
2. 一个项目经理的真实故事
(1) 痛点：混乱的任务安排
Chris 是一个开发团队的项目经理，每周一在文档里写本周任务安排。他以前用纯文字描述任务，团队成员经常遗漏事项、搞混优先级。有人问"这个任务是你的还是我的"，有人说"我不知道这个任务排在第几位"。
(2) 解法：用列表结构化任务
Chris 改用 Markdown 列表来安排任务：用有序列表标优先级，用任务列表 - [ ] 标记完成状态，用嵌套列表表示子任务。团队阅读效率大幅提升：
MARKDOWN
## 本周任务
1. **【高优先级】数据库迁移**
- [ ] 导出旧数据
- [ ] 编写迁移脚本
- [ ] 测试数据完整性
2. **【中优先级】API 文档更新**
- [x] 更新用户接口文档（已完成）
- [ ] 添加新接口示例
3. 无序列表
(1) 基本语法
无序列表用 -、* 或 + 开头，后面跟空格：
MARKDOWN
- 苹果
- 香蕉
- 橙子
* 苹果
* 香蕉
* 橙子
+ 苹果
+ 香蕉
+ 橙子
💡 提示： 三种符号效果相同。推荐全程使用
-，因为它最不易与其他语法（如斜体的 *）混淆。
(2) 多段落列表项
如果列表项包含多个段落，保持缩进一致：
MARKDOWN
- 第一项：这是主要内容。
这是该项的补充说明（与前文空了一行 + 缩进 2 空格）。
- 第二项：描述第二项内容。
更多的补充信息。
▶ 示例：用无序列表组织信息
MARKDOWN
## 项目检查清单
- **前端部分**
- 响应式布局测试
- 浏览器兼容性检查
- **后端部分**
- API 压力测试
- 数据库备份验证
- **运维部分**
- SSL 证书有效期检查
- 日志轮转配置
4. 有序列表
(1) 基本语法
有序列表用数字加句点开头：
MARKDOWN
1. 第一步：初始化项目
2. 第二步：安装依赖
3. 第三步：配置环境
4. 第四步：启动开发服务器
💡 提示： Markdown 不要求数字连续——你可以全部写
1.，渲染时自动递增编号。但推荐写真实数字，便于阅读源码时理解顺序。
(2) 从指定数字开始
某些场景需要不从 1 开始编号：
MARKDOWN
1. 前三个步骤在上一节
4. 第四步（接上文）
5. 第五步
💡 提示： 在 GitHub 上，你也可以在列表中间插入注释文字后继续编号，Markdown 会自动识别顺序。
▶ 示例：用有序列表表示步骤
MARKDOWN
## 部署流程
1. 拉取最新代码：`git pull origin main`
2. 安装依赖：`npm install`
3. 运行测试：`npm test`
4. 构建项目：`npm run build`
5. 上传到服务器：`scp -r dist/ user@server:/var/www/`
6. 重启服务：`pm2 restart app`
💡 提示： 在步骤式指南中，有序列表天然适合表示执行顺序。每步包含一个操作命令和简短说明，读者可以按顺序执行。
5. 列表嵌套
列表嵌套通过缩进实现，子列表比父列表多缩进 2 个空格（或 1 个 Tab）：
(1) 无序列表嵌套无序列表
MARKDOWN
- 编程语言
- 编译型
- C
- C++
- Rust
- 解释型
- Python
- JavaScript
- Ruby
- 数据库
- 关系型
- PostgreSQL
- MySQL
(2) 有序列表嵌套无序列表
MARKDOWN
1. 安装 Python
- 从官网下载安装包
- 勾选"Add Python to PATH"
2. 配置虚拟环境
- 创建环境：`python -m venv venv`
- 激活环境：`source venv/bin/activate`
▶ 示例：三层嵌套展示分类结构
MARKDOWN
## 前端技术栈
- **框架**
- React
- 核心概念：组件、状态、Props
- 生态：React Router、Redux
- Vue
- 核心概念：响应式数据、模板
- 生态：Vue Router、Pinia
- **样式**
- CSS
- SCSS
- Tailwind
⚠️ 注意： 嵌套不要超过 3 层，否则可读性下降。如果确实需要更深的层级，考虑用标题或表格替代。
6. 任务列表（Task Lists）
任务列表是 GFM 扩展语法，用 - [ ] 表示未完成，- [x] 表示已完成：
MARKDOWN
- [x] 完成项目初始化
- [x] 实现用户登录功能
- [ ] 编写 API 文档
- [ ] 部署到生产环境
- [ ] 性能优化
⚠️ 注意： 任务列表中的
[x] 区分大小写——[x] 和 [X] 都表示已完成。空格外必须有一个空格：- [ ] 不要写成 -[]。
▶ 示例：用任务列表跟踪项目进度
MARKDOWN
## 电商项目 Sprint 3
### 已完成 ✅
- [x] 商品列表页面
- [x] 购物车功能
- [x] 用户注册/登录
### 进行中 🔄
- [ ] 支付接口对接
- [x] 支付宝 SDK 集成
- [ ] 支付回调处理 ← 当前在进行
- [ ] 退款流程
### 待开始 📋
- [ ] 订单管理后台
- [ ] 商品搜索功能
💡 提示： 在 GitHub Issue 和 Pull Request 中使用任务列表非常高效——团队成员一眼就能看到进度。
7. 列表中的其他内容
(1) 列表中的代码块
代码块在列表内需要额外缩进（8 个空格或两个 Tab）：
MARKDOWN
- 运行测试用例：
npm run test -- --coverage
- 检查代码格式：
npx eslint src/
⚠️ 注意： 列表中的代码块不能用
``` 围栏语法（在某些解析器中会打断列表），推荐用缩进 8 空格方式。
(2) 列表中的引用
MARKDOWN
- 关键发现：
> 用户在这个页面的平均停留时间只有 12 秒。
> 主要原因是加载速度太慢。
8. 完整示例：用列表规划一个项目
TEXT
📖 仅展示
项目启动计划
Sprint 1：基础架构（第 1-2 周）
- [x] 项目初始化
1. 创建 Git 仓库
2. 配置 CI/CD
3. 搭建开发环境
- [ ] 用户系统
- [x] 注册/登录 API
- [ ] 邮箱验证 ← 优先级高
- [ ] OAuth 第三方登录
- [ ] 数据库设计
- [x] ER 图完成
- [ ] 建表脚本
- [ ] 种子数据
## Sprint 2：核心功能（第 3-4 周）
1. **商品模块**
- 商品 CRUD
- 分类管理
- 搜索功能
2. **订单模块**
- 创建订单
- 支付流程
- 订单状态管理
> **注：** 评分卡中的任务需在 Sprint 结束时全部完成。
预期效果：清晰的项目规划，按 Sprint 分组，用多种列表类型组织不同粒度的任务。
❓ 常见问题
Q 无序列表用
-、*、+ 有区别吗？A 渲染效果完全一样。推荐统一用
-，因为它不会与斜体 * 混淆，语义清晰。Q 有序列表的数字可以不连续吗？
A 可以。Markdown 会自动按顺序编号。但写正确的数字能让源码更可读。
Q 列表中的段落为什么没缩进？
A 段落必须缩进 2-4 个空格且与列表项空一行才能被正确识别为列表内容。
Q 任务列表在哪些平台支持？
A GitHub、GitLab、Obsidian 等支持 GFM 扩展的平台。Typora 也支持。但不是所有解析器都支持。
Q 列表最多可以嵌套几层？
A 没有硬性限制，但建议不超过 3 层。超过 3 层时读者视觉上难以追踪层级，应考虑用标题结构替代。
📖 小节
- 无序列表用
-，有序列表用1.，任务列表用- [ ] - 嵌套列表通过缩进 2-4 个空格实现
- 列表中的代码块需缩进 8 个空格
- 任务列表的
[x]表示已完成，[ ]表示未完成 - 列表常用于任务清单、步骤指南、分类汇总
- 推荐保持列表项长度一致，每条 1-2 行
📝 作业
-
基础题：用无序列表列出你本周要学的 5 个技术知识点，用有序列表列出学习步骤（从安装到实践），用任务列表标记你的学习进度。
-
进阶题：创建一个"项目迁移计划"，包含至少 3 个主阶段（有序列表），每个阶段包含子任务（嵌套无序列表），以及一个检查清单（任务列表）。
-
挑战题：写一个包含列表嵌套+代码块+引用三种混合内容的列表项。例如：在"部署步骤"的列表项中内嵌一段 bash 命令代码块，并在下方添加一条引用说明注意事项。
