markdownlint MD048 规则实战:用 code-fence-style 统一代码围栏风格(以 code_fence_style_backtick 测试用例为例)
markdownlint MD048 规则实战:用 code-fence-style 统一代码围栏风格(以 code_fence_style_backtick 测试用例为例)
导读
在 Markdown 文档中,围栏式代码块(fenced code block)既可以用反引号(```)也可以用波浪线(~~~)作为围栏标记,混用两种风格会让文档看起来杂乱无章。markdownlint 提供了 MD048(别名 code-fence-style)规则来强制统一这种风格。本文以仓库测试用例 test/code_fence_style_backtick.md 为切入点,完整讲解该规则的参数体系、内联配置写法、嵌套围栏场景下的判定逻辑与底层源码实现,并给出可复现的验证方法。读完本文,你将能熟练配置 code-fence-style,并能看懂 markdownlint 测试用例中 {MD048:7} 这类内联标记的含义。
一、测试用例文档说了什么:一份"可自校验"的规则说明书
code_fence_style_backtick.md 虽然看起来只是一个测试文件,但它实际上是一份高度浓缩的规则行为说明书:每个预期会触发 MD048 的行都以内联标记 {MD048:行号} 显式标注,文件末尾还附带了规则配置。其完整内容如下:
# code_fence_style_backtick
```text
This is a code block
```
~~~text
This is {MD048:7} a code block
~~~
```text
~~~
This is fine
~~~
```
~~~text
```
This is not {MD048:17}
```
~~~
<!-- markdownlint-configure-file {
"code-fence-style": {
"style": "backtick"
}
} -->
文件由四部分构成,每一部分都在验证一个具体场景:
- 第 3~5 行的反引号围栏:
style配置为backtick,因此这是"正确"写法,不产生任何报告。 - 第 7~9 行的波浪线围栏:被标记
{MD048:7},表示第 7 行(围栏起始行)将触发MD048,错误详情为 "Expected: backtick; Actual: tilde"。 - 第 11~15 行的嵌套围栏:外层是反引号,内层内容里的
~~~属于代码内容而非真正的围栏(需要两个相邻的反引号标记不能互相穿插闭合),因此"这是对的",不触发规则。 - 第 17~21 行的另一种嵌套:外层是波浪线,内部内容含
``` 同样只是内容,但由于外层风格是tilde,违背了backtick配置,第 17 行被标记触发MD048。
文件末尾的 <!-- markdownlint-configure-file ... --> 是 markdownlint 的内联配置指令,它把 code-fence-style 的 style 参数临时覆盖为 backtick,作用范围仅限本文件,无需额外配置文件即可让该测试自洽运行。
关于 {MD048:7} 内联标记的约定
在 markdownlint 的测试体系中,形如 {MD048:7} 的标记是断言语法,不是规则报错文本。其含义由测试框架解析:test/markdownlint-test-scenarios.mjs 中通过正则 /\{(MD\d+)(?::([-+]?)(\d+))?\}/g 提取规则编号与行号,与真实 lint 结果逐一比对:
{MD048:7}:直接指定期望报错行号为第 7 行;{MD048:+2}或{MD048:-1}:以标记所在行为基准做行偏移(+向下、-向上);- 不带冒号数字的
{MD048}:默认标记所在行即为报错行。
这种"期望值内联在测试文档里"的设计,使得任何人打开一个测试文件就能立刻读懂该规则在什么位置、因什么原因触发,这是理解 markdownlint 规则行为的最快途径。
二、MD048 规则本体:参数、默认值与官方文档
规则的正式定义位于 doc/md048.md:
| 项目 | 内容 |
|---|---|
| 规则编号 | MD048 |
| 别名(Aliases) | code-fence-style |
| 标签(Tags) | code |
参数 style |
string,默认 consistent,可选 backtick / consistent / tilde |
| 触发条件 | 文档中围栏代码块的围栏符号与配置风格不一致时触发 |
三个可选值的语义:
backtick:全文代码围栏必须使用反引号```;tilde:全文代码围栏必须使用波浪线~~~;consistent(默认):不做全局强制,而是以文档中第一个围栏代码块的风格为基准,后续所有围栏必须与之一致。
官方文档给出的违规示例(混用风格):
```ruby
# Fenced code
```
~~~ruby
# Fenced code
~~~
修复方式是把所有围栏统一为同一种符号:
```ruby
# Fenced code
```
```ruby
# Fenced code
```
规则设计动机(Rationale)原文为:"Consistent formatting makes it easier to understand a document."——一致的格式让文档更容易理解。
三、源码实现:MD048 是如何判定围栏风格的
规则的核心实现在 lib/md048.mjs,逻辑非常清晰,全部代码不到 50 行。其工作流程如下:
- 读取配置:
const style = String(params.config.style || "consistent")读取style参数,缺省时回退为consistent。 - 收集围栏代码块:通过
filterByTypesCached(<a href="https://link.gitcode.com/i/f1406a37ca46418241762882a65e7e65" target="_blank"> "codeFenced" ])从 micromark 解析出的 token 流中筛选出所有围栏代码块节点。该函数来自 [lib/cache.mjs,会对筛选结果做缓存,避免同一文档多次 lint 时重复遍历 token 树。 - 提取围栏序列:对每个
codeFenced节点,用getDescendantsByType(codeFenced, [ "codeFencedFence", "codeFencedFenceSequence" ])取到起始围栏的 token,拿到它的startLine(起始行号)与text(围栏符号串)。 - 判定风格:核心辅助函数
fencedCodeBlockStyleFor只看text[0]首字符——遇到~判为tilde,其余一律判为backtick:
function fencedCodeBlockStyleFor(markup) {
switch (markup[0]) {
case "~":
return "tilde";
default:
return "backtick";
}
}
- 动态基准:当配置为
consistent时,expectedStyle会在遍历到第一个围栏时被更新为该围栏的风格(expectedStyle = fencedCodeBlockStyleFor(text)),后续围栏以此为准逐一比较。 - 报错:对每个不匹配的围栏,调用
addErrorDetailIf(onError, startLine, expectedStyle, actualStyle)生成 "Expected: backtick; Actual: tilde" 形式的错误详情,且只在风格不匹配时才真正上报(addErrorDetailIf会对前后两个值是否一致做判断)。
从源码结构可以推断:判定完全基于围栏首字符,因此 ~~~ 与 ~~~~、 ``` 与 ```` 属于同一风格,规则不区分围栏长度。这一点与 CommonMark 的围栏解析规则(至少三个相同字符即可成栏)相呼应。
另外,lib/md048.mjs 声明了 "parser": "micromark",表明该规则依赖 micromark 解析器提供的 token 树工作——仓库中 micromark(4.0.2)、micromark-core-commonmark 等正是它的解析依赖(见 package.json)。
四、配置方式详解:配置文件与内联指令
方式一:外部配置文件
在 .markdownlint.json、.markdownlint.yaml 或 package.json 的 markdownlint 字段中写入:
{
"code-fence-style": {
"style": "backtick"
}
}
方式二:内联配置指令(测试用例所用)
在文档任意位置加入 HTML 注释形式的指令,仅对当前文件生效:
<!-- markdownlint-configure-file {
"code-fence-style": {
"style": "backtick"
}
} -->
这是 test/code_fence_style_backtick.md 和 test/code_fence_style_tilde.md 采用的模式——测试文件自带配置,不依赖仓库级配置即可独立运行。配套的兄弟用例 code_fence_style_tilde.md 将 style 设为 tilde,其预期报错位置与本文用例完全镜像(第 3、11 行报 "Expected: tilde; Actual: backtick"),两个文件一起覆盖了两种显式风格配置。
五、嵌套围栏:为什么 ~~~ 出现在反引号围栏内"不算违规"
这是最容易踩坑的场景,也正是测试用例第 3、4 段想说明的。看这段:
```text
~~~
This is fine
~~~
```
外层围栏是反引号,内层出现的 ~~~ 是代码内容。根据 CommonMark 规范,围栏代码块的结束标记必须与起始标记使用同一种符号(反引号围栏只能由反引号行结束),所以这里的 ~~~ 不会把代码块提前截断——它只是内容。既然不存在"第二个围栏",MD048 自然不会报错,测试标记明确写着 "This is fine"。
反之,波浪线外层围栏内的 ``` 同样只是内容,但它本身就违反了配置的 backtick 风格,于是第 17 行被标记 {MD048:17}。总结成一条经验:MD048 只检查"真正的围栏起始行",围栏内部的任何符号都不参与判定。
类似的嵌套压力测试还出现在 test/fenced_code_with_nesting.md:它用 ```` 与 ~~~~ 等多长度围栏互相包裹,验证在多层嵌套下 MD048 依然只在真正的围栏起始行(第 8、18、32、45、56、68 行)触发,而嵌套在内部的短围栏一律视为内容。这说明 MD048 对嵌套边界的判断完全交给解析器,规则自身只消费解析结果,不会误报。
六、用快照与断言验证规则行为
仓库用两层机制保证 MD048 的行为被持续验证:
- 场景测试:test/markdownlint-test-scenarios.mjs 读取所有测试 Markdown 文件,解析其中的
{MD048:行号}标记作为期望值,再调用markdownlint/promise的lint实际运行,逐条断言真实报错行号与期望一致。 - 快照对比:test/markdownlint-test-scenarios.mjs.snapshot 中保存了每个文件的完整 lint 结果快照。以
code_fence_style_backtick.md的快照为例(约第 8888 行起),真实输出的两条错误记录为:
{
"lineNumber": 7,
"ruleNames": ["MD048", "code-fence-style"],
"ruleDescription": "Code fence style",
"errorDetail": "Expected: backtick; Actual: tilde",
"severity": "error"
},
{
"lineNumber": 17,
"ruleNames": ["MD048", "code-fence-style"],
"ruleDescription": "Code fence style",
"errorDetail": "Expected: backtick; Actual: tilde",
"severity": "error"
}
这与测试文档中 {MD048:7}、{MD048:17} 两个标记完全一一对应,印证了内联标记与真实行为的一致性。需要留意的是,当前仓库版本的 MD048 快照中 fixInfo 为 null,即该规则暂未提供自动修复能力(对比可修复规则可见 lib/constants.mjs 中的 fixableRuleNames 列表)。
此外,test/MD041-MD050.md 这类多规则混测文件中也会出现 {MD048:27}、{MD048:45} 标记(配合 line-length、required-headings 等规则同时关闭),用于验证 MD048 在真实多规则环境下的协同行为。
七、本地复现与运行验证
如果你想亲手验证上述行为,在当前仓库根目录执行(需要 Node.js ≥ 22,见 package.json):
# 1. 安装依赖
npm install
# 2. 直接对测试用例运行 lint(promise API)
node --input-type=module -e "import { lint } from 'markdownlint/promise'; console.log(JSON.stringify(await lint({ files: ['test/code_fence_style_backtick.md'] }), null, 2))"
# 3. 运行完整场景测试(含快照对比与内联标记断言)
node --test test/markdownlint-test-scenarios.mjs
# 4. 若想查看解析出的 micromark token 树(了解 codeFenced 节点结构)
node test/harness.mjs test/code_fence_style_backtick.md
其中 test/harness.mjs 会打印文件的 token 树并执行 lint,非常适合观察 codeFenced、codeFencedFence、codeFencedFenceSequence 等 token 的实际结构,与 lib/md048.mjs 的取数逻辑相互印证。
结语:一条规则,三种读法
回到 test/code_fence_style_backtick.md,它既是测试用例,也是学习材料:style: "backtick" 的配置让"正确与错误"一目了然,{MD048:7} 式内联标记让预期行为不言自明,嵌套围栏段落则演示了解析器边界与规则判定的关系。配合 doc/md048.md 的参数定义与 lib/md048.mjs 的实现,你可以快速掌握 MD048 的全部行为,并将其迁移到自己的文档规范与 CI 配置中。