List with 1 tab indentation and `-`

原创2026-09-18 16:04:361,938 阅读
文章标签:开发工具格式化代码质量CLI前端

List with 1 tab indentation and -

  • Top level list item 1
  • Top level list item 2
    • Nested List item 1
    • Nested List item 2
      • Sub-Nested List item 1
      • Sub-Nested List item 2

List with 1 tab indentation and *

  • Top level list item 1
  • Top level list item 2
    • Nested List item 1
    • Nested List item 2
      • Sub-Nested List item 1
      • Sub-Nested List item 2

它刻意覆盖了三类输入特征:

1. **Tab 缩进的多层嵌套**:第一段用 1 个 Tab 表示嵌套层级(`Nested`),2 个 Tab 表示第二层嵌套(`Sub-Nested`);
2. **列表标记混用**:第一段用 `-`,第二段用 `*`;
3. **缩进字符混搭**:第二段的第三层先出现"4 个空格 + 1 个 Tab"的混合缩进(`    \t*`),用来验证 Prettier 对空格与 Tab 混杂输入的容忍度与归一化能力。

快照文件中记录的期望输出(见 `nested-tab.md - {"proseWrap":"always"} format 1` 条目)如下:

```markdown
# List with 1 tab indentation and `-`

- Top level list item 1
- Top level list item 2
  - Nested List item 1
  - Nested List item 2
    - Sub-Nested List item 1
    - Sub-Nested List item 2

# List with 1 tab indentation and `*`

- Top level list item 1
- Top level list item 2
  - Nested List item 1
  - Nested List item 2
    - Sub-Nested List item 1
    - Sub-Nested List item 2

对比输入与输出,可以提炼出 Prettier 对 Markdown 列表的 4 条固定规则:

  • 标记统一:* 全部被归一化为 -(由 列表打印器 的标记交替逻辑决定,见下文第二节);
  • 每层缩进固定为 2 个空格:1 个 Tab 的嵌套变成 2 个空格,2 个 Tab 变成 4 个空格,即使原文是"4 空格 + 1 Tab"的混合缩进,也一律收敛为 2 个空格的整数倍;
  • 标题与列表之间补空行:# Heading 之后自动插入一个空行再接列表;
  • 语义层级不变:无论缩进字符如何变化,列表的嵌套深度(顶层 → 嵌套 → 子嵌套)被完整保留,说明格式化前后 AST 结构一致。

二、源码视角:嵌套缩进是如何被重新计算的

2.1 标记交替与 * → - 的真相

很多资料只说"Prettier 把 * 改成 -",但从 src/language-markdown/print/list.js 的 getPrefix() 可以看到更精确的逻辑:

: nthSiblingIndex % 2 === 0
  ? "- "
  : "* ";

对于无序列表,标记由兄弟序号 nthSiblingIndex 的奇偶性决定:偶数位输出 - ,奇数位输出 * 。也就是说,Prettier 并不是无脑使用 -,而是在 - 与 * 之间交替,并且只对"处于兄弟关系中的第 2、4、6… 个列表"使用 *。nested-tab.md 中的两段列表恰好各自都是顶层列表中的唯一列表(兄弟序号为 0),因此都渲染为 -;而一旦出现多个同级嵌套列表,快照中就会出现交替的 *。例如 nested-checkbox.md 的快照中,嵌套子列表内部就出现了 * 标记。同理,有序列表的标记符号也按奇偶交替使用 . 与 ) 。

2.2 2 空格缩进的来源:align 与前缀长度

嵌套列表的每层缩进并不是硬编码的 "2",而是由列表前缀的字符宽度推导而来。在 printList 中,每个列表项都通过 align(" ".repeat(prefix.length), printListItem(...)) 打印:子节点(包括嵌套列表)会被 align 对齐到 prefix.length 列之后。对于无序列表,前缀恒为 2 个字符(- 或 * ),因此每一层嵌套天然缩进 2 个空格——这正是快照输出中 2/4/6 空格递增的由来。

值得注意的一个细节:有序列表的标记宽度会随数字位数变化(1. 是 3 字符,11. 是 4 字符)。对此,alignListPrefix 会依据 options.tabWidth 把前缀补足到 tabWidth 的整数倍,从而保证同一有序列表内各项的起始列对齐。相关行为可对照 align.md 的快照(1. 与 11.、1111. 并列时的对齐规则)。

2.3 Tab 在解析阶段如何参与缩进计算

nested-tab.md 之所以能证明"Tab 缩进被正确识别为嵌套",关键在于 Markdown 解析器(mdast / remark 系)遵循 CommonMark 规范的制表符规则:Tab 停止位每隔 4 列一次。1 个 Tab 使内容从第 1 列推进到第 5 列(即 4 列宽),足以让该行成为第一层列表项的子内容;2 个 Tab 推进到第 9 列,成为第二层子内容。Prettier 在打印阶段不再关心原始 Tab,而是基于解析出的 AST 层级重新输出统一的空格缩进,因此无论用户写的是 Tab、空格还是两者混合,输出都收敛为同一形式。

从源码看,transformIndentedCodeblock 用正则 /^\n?(?: {4,}|\t)/ 判定"缩进代码块"——注意这里 Tab 被等价视为 4 空格:任何以 4 个以上空格或 1 个 Tab 开头的代码节点都会被标记为 isIndented。这从侧面印证了 Prettier 内部对"Tab = 4 列"这一 CommonMark 约定的依赖。

2.4 4 空格"代码块警戒线":为什么嵌套缩进有上限

打印逻辑中有两处醒目的注释 // 4+ will cause indented code block(见 list.js 与 list.js):

  • 在 getPrefix() 中,为了满足"列表项起始位置不小于所需缩进"(minIndent),最多补 4 个尾随空格、3 个前导空格;
  • 在 printListItem() 中,clamp(options.tabWidth - listPrefix.length, 0, 3) 把对齐宽度钳制在 0~3。

原因是 CommonMark 规定:缩进 4 个空格以上的行会被解析为代码块。如果 Prettier 输出时在列表项前补了 4 个以上的空格,格式化产物再被其他 Markdown 渲染器解析时就会"语义漂移",从列表项变成缩进代码块。因此打印器宁可牺牲对齐美观,也要把续行缩进控制在 3 空格以内。这一约束贯穿 align.md、followed-by-indented-things.md、tab-width/indented-code-block.md 等多个测试用例,是理解 Prettier Markdown 输出为何"看起来间距偏小"的关键。

三、Tab 在其他 Markdown 语境中的处理

nested-tab.md 不是仓库里唯一涉及 Tab 的用例。作为补充,tab.md 覆盖了"空格 + Tab"混合缩进出现在列表项内部内容(链接、子列表、标题、围栏代码块、行内代码)时的场景,其快照显示:列表项内容区的 Tab 会被归一化,但若 Tab 位于特殊结构中(如代码块内),则会尽量保留原样,避免破坏语义。这两份测试文件共同勾勒出 Prettier 的 Tab 策略:

语境 处理方式
嵌套列表缩进(行首) 解析为层级,输出时统一为 2 空格/层
列表项正文续行 对齐到列表前缀列 + 不超过 3 空格
缩进代码块判定 Tab 等价 4 空格参与判定(`/^\n?(?: {4,}
代码块内部 保留原始缩进,不做归一化

四、如何在本仓库复现与验证

仓库使用 Jest 快照测试,验证 nested-tab.md 的行为只需运行 markdown 列表相关的测试集:

# 在仓库根目录执行
yarn jest tests/format/markdown/list

若要查看格式化的具体输出(而非仅比对快照),可以使用 Prettier 命令行直接处理该文件:

yarn prettier tests/format/markdown/list/nested-tab.md --parser markdown --prose-wrap always
登录后查看全文
prettier