markdownlint MD046（code-block-style）深入解析：缩进代码块与围栏代码块的风格一致性校验

• 开发工具
• 代码质量
• Lint
• 静态分析

本指南围绕 markdownlint 仓库中的 test/code_block_indented.md 测试用例及其规则文档 doc/md046.md，系统讲解 MD046「Code block style」规则的触发原理、三种style配置取值的行为差异、通过内联配置将文档锁定为「缩进风格」的实战方法，并结合 lib/md046.mjs 的源码与 test/markdownlint-test-scenarios.mjs.snapshot 的期望结果，还原该规则从解析到报错的完整调用链。读完本文，你将能够熟练配置并解释 MD046 在混合代码块风格文档中的全部报错行为，并能在自己的 Markdown 项目中按需启用、关闭或限定该规则。

一、MD046 是什么：代码块风格一致性规则

MD046（别名code-block-style，标签code）是 markdownlint 中负责检查同一文档内代码块风格是否统一的规则。它的核心语义是：当文档中使用了不受欢迎的、或与既定风格不一致的代码块写法时，触发违规报告。

Markdown 中声明代码块有两种原生方式：

• 缩进代码块（indented code block）：以 4 个空格（或一个 Tab）开头缩进的连续行，无需任何围栏标记；
• 围栏代码块（fenced code block）：使用```或~~~包裹的代码区。

MD046 的价值在于：这两种写法可以混用于同一篇文档，而混用往往意味着作者没有遵循统一规范。规则要求文档在两者之间做出明确选择，以保持排版一致性——正如规则文档 doc/md046.md 所述，其存在理由（Rationale）是「Consistent formatting makes it easier to understand a document.」（一致的格式让文档更易理解）。

二、测试样本全景：code_block_indented.md 的结构解读

先完整阅读被指定为核心主体的测试文件 test/code_block_indented.md：

# code_block_indented This is text. This is a code block. And here is more text ```text This is {MD046:10} also a code block.

But we'll do another:

And this will.

One last one:

This is code with an empty indented line.

这份测试样本完整覆盖了 MD046 的三种典型场景： 1. **纯缩进代码块**（第 5-6 行、第 16-17 行、第 21-23 行）：以 4 空格缩进，与配置的 `indented` 风格一致，**不触发** MD046； 2. **围栏代码块**（第 10-12 行）：使用 `` ```text `` 围栏且带语言标识，与配置的 `indented` 风格冲突，**触发** MD046，行内标记 `{MD046:10}` 指出违规行号为 10； 3. **带空行的缩进代码块**（第 23 行）：缩进代码块中间的空行仍保持缩进（该行只有 4 个空格），属于合法延续，**不触发**。 第 25-29 行通过 HTML 注释形式的内联配置 `<!-- markdownlint-configure-file -->`，将本文档的 `code-block-style.style` 设置为 `indented`，这正是第 10 行围栏代码块被判违规的原因。 ## 三、三种 style 取值的完整行为矩阵 MD046 的配置参数只有一个：`style`（字符串），默认值 `consistent`，可选值包括 `consistent`、`fenced`、`indented`。这三个取值的差异如下： | style 取值 | 判定逻辑 | 谁会被报错 | | --- | --- | --- | | `consistent`（默认） | 以**文档中第一个**代码块的风格为基准 | 后续所有与首个代码块风格不同的代码块 | | `fenced` | 强制要求全部使用围栏代码块 | 所有缩进代码块 | | `indented` | 强制要求全部使用缩进代码块 | 所有围栏代码块 | 规则文档 [doc/md046.md](https://link.gitcode.com/i/a806062846f7bcd66d38b79809f53724) 给出的默认配置违规示例展示了 `consistent` 的典型行为：第一个代码块是缩进式（`Some text.`），因此文档中后出现的围栏代码块（`` ```ruby ``）被判为违规。 同一目录下的 [test/code_block_fenced.md](https://link.gitcode.com/i/fdb687816b3be9e0957679da8f57499d) 是与本测试样本互为镜像的对照用例：该文件把 `style` 配置为 `fenced`，于是两处缩进代码块分别在第 5 行、第 16 行被标记 `{MD046}`，而围栏代码块安然无恙。两相对照可以清楚看到 `indented` 与 `fenced` 是严格对偶的两种强约束模式。 在 [test/break-all-the-rules.md](https://link.gitcode.com/i/c40b3be9c24dc06038d8750acf94d0d0) 这一「全规则破坏」压力样本中，MD046 同时在三个位置报错（第 49 行、第 73 行、第 77 行），对应 `consistent` 默认模式下围栏与缩进混合的三种情况；其中第 73 行和第 77 行还同时触发了 MD040（围栏缺少语言标识）与 MD048（围栏风格不一致），说明 MD046 常与相邻规则叠加出现，排查时可结合 [doc/md040.md](https://link.gitcode.com/i/fe9fdfd4d010257ddf5adf8911acd708) 与 [doc/md048.md](https://link.gitcode.com/i/fba0a234171c896c35dff6e67763bff5) 一起分析。 ## 四、源码级原理：MD046 如何识别两种代码块 MD046 的完整实现位于 [lib/md046.mjs](https://link.gitcode.com/i/ea84f0a5ba1cb489e57c8c391e7db2ef)，核心逻辑只有两个步骤： **第一步：从 micromark 解析结果中提取代码块 token。** 规则声明 `"parser": "micromark"`，通过 `filterByTypesCached([ "codeFenced", "codeIndented" ])` 从解析器产出的 token 流中过滤出两类代码块节点。该缓存工具定义在 [lib/cache.mjs](https://link.gitcode.com/i/f6ef7dc589e4c65a5619449219f4d16f)，在单次 lint 内按 token 类型组合缓存过滤结果，避免多条规则重复遍历。 **第二步：逐 token 比对风格并报错。** ```javascript const tokenTypeToStyle = (tokenType) => (tokenType === "codeFenced") ? "fenced" : "indented"; let expectedStyle = String(params.config.style || "consistent"); for (const token of filterByTypesCached([ "codeFenced", "codeIndented" ])) { const { startLine, type } = token; if (expectedStyle === "consistent") { expectedStyle = tokenTypeToStyle(type); } addErrorDetailIf(onError, startLine, expectedStyle, tokenTypeToStyle(type)); }

逐行拆解这段实现：

• tokenTypeToStyle将 micromark 的 token 类型映射为规则使用的风格名：codeFenced→fenced，其余（即codeIndented）→indented；
• 读取配置的style，缺省时回退为"consistent"；
• 关键机制：遍历过程中若expectedStyle === "consistent"，会先用当前第一个遇到的代码块的风格改写expectedStyle——这正是consistent语义「以首个代码块为准」在代码层面的落实：第一个代码块本身永远不报错，从第二个开始，凡是风格与首个不同的都会触发；
• 对每个 token，addErrorDetailIf在 token 的起始行（startLine）上输出错误，detail 为Expected: <期望风格>; Actual: <实际风格>。

从这段源码可以推断：报错信息必然形如Expected: indented; Actual: fenced（或反之），并附在代码块起始行。该推断已被测试快照证实——见下文第五节。

micromark 解析器的接入点在 lib/micromark-parse.mjs，它基于 micromark 及其 GFM 扩展（gfmAutolinkLiteral、gfmFootnote、gfmTable等）把 Markdown 文本转换为带startLine/endLine/text/children的 token 树，codeIndented与codeFenced两类 token 正是在这一阶段被识别出来的。如果你想直观观察 token 结构，可以运行 test/harness.mjs：

node test/harness.mjs test/code_block_indented.md

它会先递归打印每个 token 的类型与文本（缩进代码块显示为codeIndented、围栏代码块显示为codeFenced），再输出该文件经lint后得到的完整错误对象。

五、测试快照验证：期望错误与固定结果

MD046 的行为被 test/markdownlint-test-scenarios.mjs 的回归测试严格锁定。该测试套件会遍历 test 目录下所有.md文件，读取其中形如{MD046:10}的标记作为期望行号，与真实 lint 结果比对，同时用applyFixes生成修复后的文本并写入快照。

code_block_indented.md的期望结果保存在 test/markdownlint-test-scenarios.mjs.snapshot 中，其中错误信息为：

{ "lineNumber": 10, "ruleNames": [ "MD046", "code-block-style" ], "ruleDescription": "Code block style", "errorDetail": "Expected: indented; Actual: fenced", "severity": "error" }

几点值得注意：

• lineNumber为 10，与测试文件中{MD046:10}标记完全一致，落在围栏代码块```text的起始行；
• errorDetail精确呈现了「期望缩进、实际围栏」的冲突；快照中的fixed字段表明该规则不可自动修复（fixInfo为 null），修复只能由作者手工把围栏改回缩进；
• ruleInformation指向规则文档，测试时被正则替换为版本无关的占位形式；
• 该文件仅触发 1 条 MD046 错误，反向印证了第 5-6、16-17、21-23 行的缩进代码块全部合规。

六、配置与启用方式：内联注释、JSON 配置与 schema 校验

6.1 内联配置（测试样本采用的写法）

code_block_indented.md文件末尾的 HTML 注释就是 markdownlint 的文档级内联配置，作用域覆盖整个文件：

<!-- markdownlint-configure-file { "code-block-style": { "style": "indented" } } -->

等价地，也可以简写为<!-- markdownlint-config {"MD046": {"style": "indented"}} -->。行内/文件级控制还可使用<!-- markdownlint-disable code-block-style -->与<!-- markdownlint-restore -->成对指令，规则文档 doc/md046.md 的示例正文正是用这对指令包裹起来的，避免示例自身触发本规则。

6.2 配置文件中的常规写法

在.markdownlint.json/.markdownlintrc或package.json的markdownlint.config字段中，可以按规则名或别名配置：

{ "MD046": { "style": "indented" } }

也可以使用别名"code-block-style"，两者等价。关闭规则用false，调整严重级别用"error"或"warning"。

6.3 JSON Schema 的约束定义

规则的合法配置由 schema/markdownlint-config-schema.json（及严格版 schema/markdownlint-config-schema-strict.json）描述。对于code-block-style，schema 允许三种形态：布尔值（true/false）、严重级别字符串（error/warning）、或对象{ "enabled": boolean, "severity": "error"|"warning", "style": "consistent"|"fenced"|"indented" }；style枚举值限定在consistent、fenced、indented三者，默认consistent。任何超出枚举的值（如"style": "tab"）都会在配置校验阶段直接报错，而不是静默生效。仓库还内置了多种风格预设，例如 style/all.json（全部规则默认开启）与 style/relaxed.json（宽松子集），可直接作为配置起点。

6.4 相关规则的联动排查

与 MD046 经常同时出现的邻居规则包括：

• MD040fenced-code-language：要求围栏代码块必须带语言标识；
• MD048code-fence-style：要求围栏符号统一为反引号或波浪号；
• MD014dollar-signs：检查缩进代码块中命令前的$前缀，test/code_block_dollar.md 中同时出现{MD014}与{MD046:34}标记，说明一份样本可同时暴露多条代码块相关规则。

排查时建议先看 MD046 是否命中，再结合 MD040/MD048 判断是「风格混用」还是「围栏细节不合规」。

七、实践建议与验证方法

1. 选择团队统一的代码块风格：若仓库文档以围栏为主（现代 README 的常态），配置{"MD046": {"style": "fenced"}}；若文档多为手动缩进的短片段，则用indented。两种强约束都能让「混用」在 CI 中第一时间暴露。
2. 善用consistent的自动跟随：默认模式下规则会自动以首个代码块为准，适合风格尚未定型的存量文档——只要后续写法与首个一致即可放行。
3. 本地验证：在仓库根目录执行

node test/harness.mjs test/code_block_indented.md

可同时看到 micromark token 结构与完整 lint 错误输出；执行场景测试套件可确认快照一致：

node --test test/markdownlint-test-scenarios.mjs

4. 记忆要点：code_block_indented.md是 MD046 在indented强约束下的「标准答案」样本——除刻意保留的围栏违规外，所有缩进代码块（含空行缩进）都应零报错；理解它，就等于理解了 MD046 的全部判定逻辑。

相关文件索引

• 规则文档：doc/md046.md、规则汇总 doc/Rules.md
• 规则实现：lib/md046.mjs
• 测试样本：test/code_block_indented.md、对照样本 test/code_block_fenced.md、压力样本 test/break-all-the-rules.md
• 测试框架与快照：test/markdownlint-test-scenarios.mjs、test/markdownlint-test-scenarios.mjs.snapshot、test/harness.mjs
• 解析器接入：lib/micromark-parse.mjs、token 缓存 lib/cache.mjs
• 配置 Schema：schema/markdownlint-config-schema.json、schema/markdownlint-config-schema-strict.json
• 风格预设：style/all.json、style/relaxed.json

• 开发工具
• 代码质量
• Lint
• 静态分析