前置知识: Markdown

Markdown 任务列表

5 min入门

GFM 任务列表语法：复选框的识别规则、GitHub 交互行为、嵌套与实战场景。

认知导入（Layer 1 进阶层） 前置知识：006 列表语法（本篇是列表的特例）。 边界说明：任务列表是 GFM 扩展，纯 CommonMark 渲染器只会显示字面的 [ ]；本篇讲清它在哪些平台”可点击”、哪些平台只是普通文本。 强制练习：写一个三行的任务清单，把 [ ] 后面的空格删掉，观察复选框是否消失——空格同样是语法的一部分。

1. 基本语法

任务列表就是在普通列表项的开头加一个复选框标记：[ ] 表示未完成，[x] 表示已完成。

- [ ] 编写单元测试
- [x] 完成需求评审

混合使用表示一个进行中的清单：

- [x] 拉取最新代码
- [x] 修改登录逻辑
- [ ] 提交代码评审
- [ ] 部署测试环境

在支持 GFM 的平台（GitHub、GitLab 等）上，勾选状态渲染为复选框；在纯 CommonMark 渲染器上则原样显示 - [ ] 编写单元测试 这样的文本。

2. 语法识别规则

任务列表的识别条件比看上去严格，以下规则来自 GFM 规范并经 GitHub 行为验证。

2.1 方括号内只能是空格或 x

- [ ] 未完成任务（方括号内一个空格）
- [x] 已完成任务
- [X] 大写 X 同样表示完成（不区分大小写）

2.2 标记后必须有空格

[ ] 或 [x] 之后必须至少跟一个空白字符，否则不构成任务列表项：

- [ ]任务（错误：紧贴文本，整行是普通列表项）
- [] 错误（方括号内没有空格，不构成任务）
- [ ] 正确任务

2.3 标记必须位于列表项内容的最前面

复选框只在列表项第一个块级内容开头被识别，写在句中只是普通文本：

- 先完成 [ ] 这一步（错误：标记不在开头，按字面显示）
- [ ] 先完成这一步（正确）

此外它要求列表项的第一个块是段落：如果列表项直接以嵌套列表开头（没有文字），也不会被识别为任务。

2.4 与普通列表项混用

同一列表中任务项与普通项可以混合，普通项渲染为普通圆点：

- 普通列表项
- [ ] 待办任务项
- [x] 已完成任务项

3. 嵌套与有序任务

3.1 缩进子任务

与普通列表一样，用缩进表达层级（一般缩进 2 个空格对齐无序列表内容）：

- [ ] 后端开发
  - [x] 设计 API 接口
  - [ ] 实现业务逻辑
- [ ] 前端开发
  - [ ] 页面布局

3.2 有序任务列表

数字列表同样可以承载复选框：

1. [x] 需求确认
2. [ ] 方案设计
3. [ ] 编码实现

有序任务的子项需要缩进到与父项内容对齐（通常 3 个空格）：

1. [x] 准备阶段
   1. [x] 收集资料
   2. [ ] 整理清单
2. [ ] 执行阶段

4. GitHub 上的交互行为

这是任务列表区别于普通列表的核心价值，几个行为值得了解：

  • 可点击勾选：Issue、Pull Request、Discussion 的正文与评论，以及仓库内 Markdown 文件的预览页，复选框都可以直接点击切换。
  • 点击会写回源码：在文件预览页点击复选框，GitHub 会自动创建一个修改该文件的提交；在 Issue/评论中点击，则以你的名义编辑该条内容。因此不要把任务列表当作”只属于自己”的草稿——任何能编辑该内容的人都可能改动勾选状态。
  • 进度汇总：Issue 正文中包含任务列表时，Issue 列表页会显示”N of M tasks”之类的完成进度，方便跟踪。
  • 引用块内的限制：写在 > 引用块里的任务列表，GitHub 通常渲染为不可交互的复选框（仅展示状态）。
  • 表格内不生效：GFM 表格单元格按行内语法解析，| [x] | 只会显示字面文本 [x]，不会渲染复选框。需要在表格里表达状态时，用文字”完成/待办”更可靠。

5. 与其他行内元素组合

任务文本中可以包含强调、链接、行内代码等行内元素：

- [ ] **核心功能**：实现支付模块
- [x] 阅读 [需求文档](https://example.com/spec)
- [x] 实现 `getUserInfo` 接口
- [x] ~~完成支付模块~~（需求变更，已取消）

最后一行是任务列表与删除线的经典组合：勾选表示”这条已处理”，删除线表示”处理方式是取消”，括号补充原因（详见 markdown/120-Strikethrough）。

6. 渲染器支持差异

平台 / 渲染器复选框渲染可点击交互说明
GitHub支持支持点击写回源码，见第 4 节
GitLab支持支持Issue 与 MR 中同样可勾选
Obsidian支持支持配合 Tasks 等插件可加截止日期、循环任务
VS Code 预览支持否（只读）源码编辑 + 预览查看
纯 CommonMark 渲染器不支持无原样显示 [ ] 文本

Obsidian 等工具还会在任务项后追加 #标签、日期等私有扩展语法用于任务管理，这些只在对应工具内有意义，跨平台分发时应避免依赖。

7. 实战场景

7.1 发布检查清单

## 发布前检查清单

- [x] 全部测试通过
- [x] CHANGELOG 已更新
- [ ] 版本号已升级
- [ ] 标签已推送

7.2 Pull Request 模板

把任务列表写进 .github/pull_request_template.md，让作者逐项自查：

- [ ] 我已阅读贡献指南
- [ ] 新增代码有对应测试
- [ ] 变更已写入 CHANGELOG

7.3 手动进度统计

Markdown 没有内建进度计算，需要自动进度时靠约定写法（写进标题）或外部工具汇总：

## 项目进度 2/4
- [x] 模块 A
- [x] 模块 B
- [ ] 模块 C
- [ ] 模块 D

8. 常见陷阱

  1. [ ] 后少了空格：- [ ]任务 不是任务项，整行变普通列表。
  2. 方括号内忘了空格：- [] 不构成复选框。
  3. 在表格里用复选框：不渲染，改用文字状态。
  4. 误以为勾选只是本地视图：在 GitHub 上点击复选框会真实修改文件或评论，多人协作时注意。
  5. 缩进不一致导致层级丢失：嵌套任务的缩进必须与父项内容对齐，混用制表符与空格常见错乱。
  6. 把任务列表当数据库用：大量状态、时间、负责人塞进任务文本后难以统计；结构化数据应交给 Issue、看板等工具。

小结

  • 初学者要点：- [ ] 未完成、- [x] 已完成；方括号后加空格；缩进子任务；GitHub/GitLab 上可直接点击勾选。
  • 进阶注意：任务是 GFM 扩展，纯 CommonMark 只显示字面文本；标记必须在列表项内容最前且第一个块是段落；表格内不渲染复选框；GitHub 点击勾选会产生真实提交或评论编辑。