Markdown星号列表缩进失效，如何正确嵌套无序列表？

Question

**Markdown星号列表缩进失效？这是常见排版陷阱！** 在Markdown中，仅靠空格或Tab键缩进 `*` 项（如 `* 一级 * 二级`）无法触发嵌套——解析器会将其视为同级列表项。正确嵌套必须满足：**每级子列表前需用至少1个空格（推荐2–4个）对齐其父项的起始符号位置**，且子项符号（`*`/`-`/`+`）前**不能有其他字符（包括制表符）**。例如： ```markdown * 一级项 * 二级项（✅ 正确：2空格缩进） * 三级项（✅ 正确：再缩进2空格） * 另一个一级项 ``` ⚠️ 常见失效原因：混用Tab与空格、缩进不足（少于1空格）、子项前误加标点或多余空格。部分编辑器（如Typora旧版）默认用Tab缩进，需在设置中启用“插入空格代替Tab”。建议统一使用2空格缩进，并借助预览实时校验。嵌套层级建议≤4级，避免可读性下降。

Answer 1

```html

一、现象层：为什么“看着缩进了，却没嵌套”？

这是最直观的困惑——用户在编辑器中按 Tab 或敲了多个空格，视觉上明显右移，但预览中仍为扁平列表。根本原因在于：Markdown 解析器不依赖“视觉缩进”，而依赖“语法对齐规则”。CommonMark 规范（v0.30+）明确定义：子列表项必须与父项的 内容起始位置 对齐（而非符号位置），且缩进必须由空格构成，\t 不被普遍支持。

二、规范层：CommonMark 与 GitHub Flavored Markdown（GFM）的差异解析

特性	CommonMark 0.30+	GFM（GitHub / VS Code 预览）
Tab 缩进支持	❌ 明确不支持（视为普通字符）	⚠️ 部分兼容（等效为 4 空格），但行为不稳定
最小缩进要求	✅ ≥1 空格（对齐父项内容首字符）	✅ 同 CommonMark，但容忍 1–2 空格偏差
混合符号嵌套	✅ * - + 可混用（如 * A\n - B）	✅ 支持，但建议统一以提升可维护性

三、工具链层：编辑器与构建系统如何“悄悄破坏”嵌套

• Typora（v1.1 以前）：默认启用 Tab 缩进，且未自动转换为空格 → 导致导出 HTML 时层级丢失；需手动开启 Preferences → Editor → Insert spaces instead of tab。
• VS Code + Markdown All in One：默认 tabSize: 4，但若用户用 Shift+Tab 反向缩进，易引入不可见 \u0008 或混合空格 → 建议配置 "editor.detectIndentation": false 并强制 "editor.insertSpaces": true。
• Hugo / MkDocs 构建流程：若源文件经 Git LFS 或 IDE 自动格式化（如 Prettier 的 markdown/indent 规则），可能将 2 空格转为 4 空格，打破原有对齐逻辑 → 需在 .prettierrc 中显式禁用："markdownIndentation": "tab"（不推荐）或改用空格校验脚本。

四、诊断层：三步定位失效根源

1. 可视化空格：在 VS Code 中按 Ctrl+Shift+P → “Toggle Render Whitespace”，观察是否混入 →（Tab）或 ·（空格）；
2. 结构验证：粘贴到 CommonMark Dingus，比对 AST 输出中 list_item 的 children 层级；
3. 字节级检查：运行 xxd -g1 your.md | grep -A5 "2a20"（查找 * 前的十六进制字节），确认缩进字符为 20（空格）而非 09（Tab）。

五、工程实践层：建立可持续的嵌套治理机制

面向 5+ 年经验工程师，需超越“手写修复”，转向自动化防护：

# .editorconfig（根目录）
[*.{md,markdown}]
indent_style = space
indent_size = 2
trim_trailing_whitespace = true
insert_final_newline = true

# pre-commit hook（.pre-commit-config.yaml）
- repo: https://github.com/executablebooks/mdformat
  rev: 0.7.17
  hooks:
    - id: mdformat
      args: [--number, --wrap, 88]

六、架构层：当 Markdown 成为前端 DSL —— 嵌套失效的连锁影响

在基于 Markdown 构建文档即代码（Docs-as-Code）的系统中（如 Docusaurus v3 + MDX），列表嵌套常映射为：

graph TD
  A[Markdown * item] --> B[MDX AST node]
  B --> C{isNested?}
  C -->|Yes| D[React Component: CollapsibleList]
  C -->|No| E[Plain ul/li → 无交互]
  D --> F[Accessibility: aria-expanded]
  E --> G[SEO: missing semantic hierarchy]

一旦缩进失效，不仅 UI 层级坍塌，更导致 WCAG 1.3.1（信息与关系）合规失败，且搜索爬虫无法识别内容隶属结构——这已超出排版问题，升级为可访问性与 SEO 架构风险。

```