markdownlint MD048 规则实战:用 code-fence-style 统一代码围栏风格(以 code_fence_style_backtick 测试用例为例)

原创2026-10-15 19:08:552,934 阅读
文章标签:开发工具Lint静态分析代码质量

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"
  }
} -->

文件由四部分构成,每一部分都在验证一个具体场景:

  1. 第 3~5 行的反引号围栏:style 配置为 backtick,因此这是"正确"写法,不产生任何报告。
  2. 第 7~9 行的波浪线围栏:被标记 {MD048:7},表示第 7 行(围栏起始行)将触发 MD048,错误详情为 "Expected: backtick; Actual: tilde"。
  3. 第 11~15 行的嵌套围栏:外层是反引号,内层内容里的 ~~~ 属于代码内容而非真正的围栏(需要两个相邻的反引号标记不能互相穿插闭合),因此"这是对的",不触发规则。
  4. 第 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 行。其工作流程如下:

  1. 读取配置:const style = String(params.config.style || "consistent") 读取 style 参数,缺省时回退为 consistent。
  2. 收集围栏代码块:通过 filterByTypesCached(<a href="https://link.gitcode.com/i/f1406a37ca46418241762882a65e7e65" target="_blank"> "codeFenced" ]) 从 micromark 解析出的 token 流中筛选出所有围栏代码块节点。该函数来自 [lib/cache.mjs,会对筛选结果做缓存,避免同一文档多次 lint 时重复遍历 token 树。
  3. 提取围栏序列:对每个 codeFenced 节点,用 getDescendantsByType(codeFenced, [ "codeFencedFence", "codeFencedFenceSequence" ]) 取到起始围栏的 token,拿到它的 startLine(起始行号)与 text(围栏符号串)。
  4. 判定风格:核心辅助函数 fencedCodeBlockStyleFor 只看 text[0] 首字符——遇到 ~ 判为 tilde,其余一律判为 backtick:
function fencedCodeBlockStyleFor(markup) {
  switch (markup[0]) {
    case "~":
      return "tilde";
    default:
      return "backtick";
  }
}
  1. 动态基准:当配置为 consistent 时,expectedStyle 会在遍历到第一个围栏时被更新为该围栏的风格(expectedStyle = fencedCodeBlockStyleFor(text)),后续围栏以此为准逐一比较。
  2. 报错:对每个不匹配的围栏,调用 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 的行为被持续验证:

  1. 场景测试:test/markdownlint-test-scenarios.mjs 读取所有测试 Markdown 文件,解析其中的 {MD048:行号} 标记作为期望值,再调用 markdownlint/promise 的 lint 实际运行,逐条断言真实报错行号与期望一致。
  2. 快照对比: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 配置中。

登录后查看全文
markdownlint