精通Markdown列表:CommonMark与GitHub Flavored Markdown (GFM) 缩进标准
Markdown列表渲染的技术基础
Markdown已成为现代软件文档、技术规范书、个人知识库以及开发者日常沟通的标准标记语言。虽然单层无序列表(- 项目)和有序列表(1. 项目)看似简单,但在构建深度嵌套的多层文档大纲时,会引入极高格式复杂度。不同的Markdown解析器(如CommonMark、GitHub Flavored Markdown (GFM)、Python-Markdown和Pandoc)在列表符号选择、Tab与空格比例以及子块缩进方面都有着严格而微妙的规则。
当列表在不同的文本编辑器(如VS Code、Sublime Text、Xcode、Apple Notes或Microsoft Word)之间相互粘贴时,经常会出现隐蔽的缩进错误。子项上只要缺失一个空格,Markdown编译器就会将嵌套的子节点误判为主层级项目或孤立的段落块。Utiliome的嵌套列表与缩进格式化工具通过解析输入文本的抽象语法树(AST),并重新生成符合规范的标准Markdown,彻底消除这些解析异常。
缩进规则:2空格 vs 4空格指南
技术文档设计中最常见的争议之一是:子列表究竟应该按层级缩进2个空格还是4个空格。这取决于目标Markdown解析器的规范要求:
2空格缩进规则(标准GFM与Prettier): 在GitHub、Docusaurus、Nextra和Obsidian等现代Web文档生态系统中,每层缩进2个空格是公认的标准。2空格规范可使子项内容与父项文本的起始位置对齐:
- 顶层项目 1 - 嵌套子项目 1.1 - 嵌套子项目 1.2 - 深度嵌套孙项目 1.2.1 - 顶层项目 24空格缩进规则(严格CommonMark与Python-Markdown): 严格的CommonMark实现要求有序列表内部的子块、代码片段和嵌套列表必须缩进4个空格(或1个完整的Tab),以确保父块的包含关系:
1. 工作流中的第一步 - 关联的子项目 A - 关联的子项目 B 2. 工作流中的第二步Tab与空格混用的陷阱: 混用物理Tab字符(
\t)与ASCII空格字符(\x20)是导致Markdown文档渲染排版崩溃的首要原因。Web渲染引擎对Tab的解析并不一致(通常显示为4或8个字符宽度),导致嵌套项出现视觉错位。Utiliome会根据您的配置偏好,自动将所有Tab字符转换为统一的空格字符串。
项目符号规范化与有序序列重排
Markdown支持三种不同的无序列表符号:连字符(-)、星号(*)和加号(+)。虽然三者都能生成有效的HTML无序列表元素(<ul>),但在同一文档中混用不同符号会造成视觉混乱,且无法通过自动化Lint检查(例如 markdownlint 的 MD004 规则)。
此外,在反复编辑的过程中,有序列表的编号经常被打乱。作者经常在列表中间粘贴新项,或者依赖重复的 1. 语法:
<!-- 未格式化 / 混乱的输入 -->
* 特性 A
- 特性 B
+ 特性 C
1. 初始步骤
1. 第二步(从草稿复制)
4. 顺序混乱的步骤
Utiliome格式化工具会将所有无序列表符号统一为您选择的字符(例如全部规范为 -),并将有序列表重新重排为连续递增的数字(1.、2.、3.),或根据您团队的代码规范统一重排为干净的增量形式。