前置知识: Markdown

Markdown 引用与嵌套列表

6 min入门

引用块的层级与懒延续规则、嵌套列表的缩进判定、引用与列表互相嵌套的组合写法。

认知导入（Layer 1 进阶层） 前置知识：006 列表语法。 边界说明：引用（>）用于转述与摘录；嵌套列表依赖缩进，缩进不一致会破坏层级。本篇把两个最依赖”空白字符”的语法放在一起讲。 强制练习：用 > 写一段引用，再在引用内嵌套一个列表；然后故意把缩进改错，观察层级如何塌掉。

1. 引用基础

1.1 基本写法

> 这是一段引用内容

1.2 多行与多段

每行都以 > 开头即为连续引用；引用内用只含 > 的空行分隔段落：

> 第一行引用
> 第二行引用
>
> 第二段引用（与上一段之间有空行）

1.3 懒延续：> 可以省略

引用的后续行即使不写 > 也会被并入引用（这叫懒延续，lazy continuation）：

> 这行有引用符
这行没有，但仍属于引用

渲染后两行同属一个引用块。这个特性既是便利也是陷阱：引用结束后必须留一个真正的空行，否则紧跟着的普通段落会被”吸”进引用里。

2. 引用嵌套与其他元素

2.1 引用嵌套引用

>> 表示二层引用，>>> 三层，以此类推：

> 外层引用
>> 内层引用
>>> 更深层引用

2.2 引用内含标题、列表与行内格式

引用块可以承载几乎所有块级元素，每行前加 > 即可：

> ## 引用内标题
> - 列表项一
> - 列表项二
>
> **加粗** 与 *斜体* 均可

引用内的代码块同样可行，围栏式代码块每行都缩进在 > 之后：

> 示例：
>
> ```bash
> npm install
> ```

2.3 引用打断段落

> 行可以紧跟在段落文字之后直接开始引用（无需空行）——这与”引用的懒延续会吞掉后续段落”是一体两面：段落后的 > 行成为引用的开头，而引用后的普通段落则可能被吸进引用。写完引用永远留一个空行，是最简单可靠的纪律。

2.4 列表项内放引用

> 缩进到列表项内容列即可：

- 项目一
  > 项目一的说明引用
- 项目二

GitHub、Obsidian 的警报块/Callout（见 markdown/180-AdmonitionCallout）都是把提示内容装进引用块的产品化形态。

3. 嵌套列表

3.1 缩进决定层级

无序列表的子项缩进 2 空格（与父项内容起始列对齐）：

- 父项一
  - 子项一
  - 子项二
- 父项二

有序列表的标记 1. 占 3 列，子项缩进 3 空格：

1. 父项
   1. 子项一
   2. 子项二
2. 父项二

3.2 缩进规则的本质

CommonMark 的判定标准是”缩进到父项内容的起始列”，不是固定死数：

  • - 项（标记 2 列）子列表缩进 2 空格；
  • 1. 项（标记 3 列）子列表缩进 3 空格；
  • 10. 项（标记 4 列）子列表缩进 4 空格。

缩进少于该列数时，子项会被解析为父项的同级，层级塌掉。反过来要小心另一条规则：相对内容列再缩进 4 空格就是代码块。所以”嵌套列表统一缩进 4 空格”的老建议在 - 项上有风险——恰好触到代码块阈值或层级错乱，不同渲染器表现不一。务实做法：统一用”对齐内容列”的最小缩进（- 项 2 空格、1. 项 3 空格），并全程只用空格不用制表符。

3.3 多级嵌套

每加深一层，缩进累加一个内容列：

- 一级
  - 二级
    - 三级
      - 四级

层级没有任何渲染上限，但归属判断全靠数空格——三层以上建议改用小标题或拆分列表，读者与维护者都会受益。

缩进深度与制表符的关系值得一提：CommonMark 会把制表符展开到下一个 4 列倍数（制表位），所以”一个 Tab”在列 0 处等价 4 空格、在列 2 处等价 2 空格。理论上 Tab 可以恰好对齐内容列，但不同编辑器的 Tab 显示宽度与转换设置各异，混用必然错乱——列表缩进只用空格，并在编辑器开启”Tab 转空格”。

3.4 任务列表嵌套

任务列表（见 markdown/170-TaskList）就是带复选框的列表，嵌套规则相同：

- [x] 主任务
  - [x] 子任务一
  - [ ] 子任务二

4. 列表项内的代码块

列表项内放代码块有两种方式，推荐围栏式（不受缩进阈值影响）：

- 项目一

  ```js
  const x = 1;
  console.log(x);
  ```

- 项目二

缩进式代码块也可以用，但代码必须相对列表项内容列再缩进 4 空格（- 项即 6 空格起），一旦差一格就变普通段落：

- 项目一

      const x = 1;
      console.log(x);

- 项目二

5. 紧凑与松散列表

项与项之间有无空行，决定列表渲染为紧凑（<li> 内不分段落）还是松散（每个项包一层段落 <p>，行距更大）：

// 紧凑：项间无空行
- 项一
- 项二

// 松散：项间有空行
- 项一

- 项二

两种写法语法都合法，只是视觉行距不同。同一文档保持一种风格即可（markdownlint 的 MD032 等规则可以帮团队统一）。

6. 常见陷阱

  1. 引用后不留空行：懒延续会把后面的普通段落吸进引用；引用结束后永远留一个空行。
  2. 制表符参与缩进：列表缩进必须用空格，制表符在不同编辑器宽度不同，渲染极易错乱。
  3. 无序列表套 4 空格：内容列对齐只需 2 空格，多出的缩进在部分渲染器上会把子项变代码块。
  4. 代码块缩进差一格：缩进式代码块要求精确的缩进量，优先使用围栏代码块。
  5. > 后多打了空格导致层级判断错误：> 文本 与 >文本 的差异多数渲染器宽容，但嵌套引用 >> 中间的空格数量会影响层级视觉，保持一致即可。
  6. 在有序列表项内换行不缩进：1. 项的续行需要缩进 3 空格，顶格写会被切成新段落。

小结

  • 初学者要点：引用每行加 >，嵌套引用用 >>；无序列表嵌套缩进 2 空格、有序列表缩进 3 空格；引用和列表结束后都留空行，防止后续内容被”吸进去”。
  • 进阶注意：懒延续让 > 可以省略但也制造粘连；缩进的本质是”对齐父项内容列”，4 空格是代码块阈值而非列表标准；列表内代码块优先用围栏式；紧凑与松散列表影响渲染行距，团队保持一致。