Markdown列点为何不显示正确层级？

Question

在使用 Markdown 编写文档时，常遇到列表层级显示异常的问题：嵌套列表未正确缩进，导致子项与父项平级显示。问题根源通常在于缩进不规范——Markdown 要求嵌套列表项至少用 2 到 4 个空格或一个制表符相对于父级缩进。若空格数不足或混用空格与制表符，解析器将无法识别层级关系，从而破坏结构。确保编辑器显示不可见字符并统一缩进方式可有效避免此问题。

Answer 1

1. 问题初探：Markdown 列表层级显示异常的常见现象

在使用 Markdown 编写技术文档、API 接口说明或项目需求文档时，开发者常会遇到列表嵌套结构错乱的问题。例如：

• 一级任务项
• 二级子任务
• 另一个一级任务

从书写意图上看，“二级子任务”应作为“一级任务项”的子项，但由于缩进不当，解析器将其视为同级列表项，破坏了逻辑结构。

2. 深层剖析：Markdown 解析器如何处理列表层级

Markdown 的语法解析依赖于严格的空白字符规则。以下是关键机制：

1. 父级列表项后，子列表必须通过至少 2 个空格 或 1 个制表符（Tab） 进行缩进。
2. 推荐缩进为 4 个空格，以增强可读性和兼容性。
3. 不同解析器（如 CommonMark、GitHub Flavored Markdown）对缩进容忍度略有差异。

示例代码如下：

- 主任务
    - 子任务1
    - 子任务2
      - 子子任务

3. 常见错误模式与识别方法

错误类型	表现形式	修复建议
缩进不足	仅使用1个空格	改为4个空格或1个Tab
空格与Tab混用	视觉对齐但实际不一致	统一为全空格或全Tab
编辑器隐藏不可见字符	难以定位缩进问题	开启“显示空格和制表符”功能

4. 技术实践：构建健壮的 Markdown 缩进规范

为避免此类问题，团队应建立标准化写作流程：

• 使用支持语法高亮和不可见字符显示的编辑器（如 VS Code、Typora）
• 配置编辑器自动将 Tab 转换为 4 个空格
• 集成 Prettier 或 Remark-lint 进行自动化格式校验

VS Code 配置片段示例：

{
  "editor.tabSize": 4,
  "editor.insertSpaces": true,
  "editor.renderWhitespace": "boundary"
}

5. 可视化分析：嵌套列表结构的 Mermaid 流程图表示

以下 Mermaid 图展示了正确缩进所对应的逻辑层级关系：

graph TD
    A[主任务] --> B[子任务1]
    A --> C[子任务2]
    C --> D[子子任务]

该图清晰表达了父子节点之间的归属关系，对应于正确的 Markdown 层级结构。

6. 高阶策略：自动化检测与 CI/CD 集成

对于大型文档项目，手动检查不现实。建议引入静态分析工具链：

1. 使用 markdownlint-cli 检测缩进一致性
2. 在 Git 提交前通过 Husky 触发 lint 检查
3. 在 CI 管道中加入文档质量门禁

示例脚本命令：

npx markdownlint '**/*.md' --config .markdownlint.json