深入解析 markdownlint MD043 的 "?" 通配符:以 required-headings-question-last 测试为引的标题结构强制校验实战

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

深入解析 markdownlint MD043 的 "?" 通配符:以 required-headings-question-last 测试为引的标题结构强制校验实战

本篇指南以仓库测试用例 test/required-headings-question-last.md 为切入点,系统讲解 markdownlint 规则 MD043(别名 required-headings)中特殊通配符 "?" 的使用方法:如何在 headings 配置列表的末尾放置 "?",以表示"此处必须恰好存在一个标题,但内容可以任意变化"(典型场景如项目名)。读完本文,你将掌握 "?"、"*"、"+" 三种通配符的语义差异、在列表不同位置的行为边界,以及如何通过行内配置注释与外部配置文件为整组文档强制统一的标题结构。

一、先看关联测试:required-headings-question-last.md 在验证什么

仓库测试目录下的 required-headings-question-last.md 是一个自包含的验证样例,文件正文只有 15 行,完整内容如下:

# Project Name

## Description

## Examples

<!-- markdownlint-configure-file {
  "required-headings": {
    "headings": [
      "# Project Name",
      "## Description",
      "?"
    ]
  }
} -->

该文件的要点拆解如下:

  • 文档正文依次出现 # Project Name(一级标题)、## Description、## Examples(两个二级标题);
  • 文件末尾通过 HTML 注释形式的行内配置指令 <!-- markdownlint-configure-file ... --> 为本文件单独注入 MD043 配置;
  • headings 数组配置为 ["# Project Name", "## Description", "?"],其中前两项是精确匹配的固定标题,最后一项是通配符 "?"。

该用例的意图是验证:当 "?"" 位于配置列表末尾时,它代表"最后一个必需标题的内容不受约束"。## Examples 这一实际存在的标题正好填补了 "?"" 的位置,因此文档不应产生任何 MD043 违规。换句话说,这个测试文件是"通过"(pass)场景——它用于证明 "?"" 在末尾时不会强制某个具体的标题文本。

与之形成对照的,是仓库中另外两个"失败"(fail)场景:

  • required-headings-question-extra.md:正文只有 # Project Name 与 ## Description,配置同样以 "?"" 结尾,文件末尾标注了 {MD043:+1}(即预期在第 15 行附近产生一条 MD043 错误),因为 ## Examples 缺失,"?"" 对应的位置没有标题可匹配;
  • required-headings-question-missing.md:正文为 # Project Name 与 ## Examples,配置为 ["# Project Name", "?", "## Examples"],同样标注 {MD043:+1},说明 "?"" 位于中间时同样要求其后有标题承接。

这种"每个测试文件自带 {MD043:+N} 期望标记"的编排方式,是 markdownlint 测试体系的标准做法,便于后续回归验证。

二、MD043 规则速览:参数、别名与适用场景

在深入通配符之前,先建立规则的整体认知。根据规则文档 doc/md043.md 与规则实现 lib/md043.mjs,MD043 的基本信息如下:

项目 内容
规则编号 MD043
别名(Aliases) required-headings
标签(Tags) headings
解析器 micromark(规则头声明 "parser": "micromark")
参数 headings 标题列表,类型 string[],默认 []
参数 match_case 是否严格匹配标题大小写,类型 boolean,默认 false

该规则的触发条件与核心思想:当文件中的标题序列与 headings 参数给定的列表不一致时触发错误。它可以用来为一组内容相似的文档强制统一的标题结构(Rationale:Projects may wish to enforce a consistent document structure across a set of similar content)。

一个值得注意的实现细节是:规则函数开头对配置做了快速短路处理(lib/md043.mjs):

const requiredHeadings = params.config.headings;
if (!Array.isArray(requiredHeadings)) {
  // Nothing to check; avoid doing any work
  return;
}

即当 headings 不是数组时(例如未配置该规则),规则直接返回、不做任何检查,避免无效开销。这也解释了为什么默认值 <a href="https://link.gitcode.com/i/55f37b442bb64c8c6f39fb4940dec16c" target="_blank">] 时文档只要包含任意标题就可能报错(空列表意味着"除通配符外没有必需标题"),详见 [test/required-headings-none.md 中 {MD043} 的期望标记。

三、"?"" 通配符的语义:源码级解读

"?"" 是 MD043 三种特殊值之一。规则实现 lib/md043.mjs 中通过 getExpected() 逐个取出期望标题:

const getExpected = () => String(requiredHeadings[i++] || "[None]");

而 "?"" 的分支位于匹配主循环中(lib/md043.mjs):

} else if (expected === "+") {
  matchAny = true;
} else if (expected === "?") {
  // Allow current, match next
}

从源码注释 "Allow current, match next" 可以确认 "?"" 的精确语义:允许当前实际标题与期望列表中的任意内容(不做文本比较),然后继续匹配下一个期望条目。这与普通字符串期望(走 handleCase(expected) === handleCase(actual) 的大小写不敏感比较分支)有本质区别。

对照规则文档 doc/md043.md 的表述:"?"" 意为 "exactly one unspecified heading"(恰好一个未指定的标题)。文档给出的典型示例场景是项目名类标题:

# Project Name
## Description
## Examples

对应的配置为:

[
  "?",
  "## Description",
  "## Examples"
]

此时 # Project Name 的具体内容(只要是一个一级标题)即可匹配 "?"",而 ## Description、## Examples 仍需精确存在。由于默认 match_case: false,普通字符串匹配不区分大小写;"?"" 则完全跳过文本比较,只关心"是否存在一个标题"。

四、"?"" 在列表不同位置的行为对比

结合仓库中的四个 required-headings-question-* 测试文件,可以完整还原 "?"" 在不同位置的行为矩阵:

测试文件 headings 配置 正文标题 期望结果
question-last.md ["# Project Name", "## Description", "?"] # Project Name、## Description、## Examples 通过(无错误)
question-first.md ["?", "## Description", "## Examples"] 同上 通过(无错误)
question-middle.md ["# Project Name", "?", "## Examples"] 同上 通过(无错误)
question-extra.md ["# Project Name", "## Description", "?"] # Project Name、## Description 失败({MD043:+1})
question-missing.md ["# Project Name", "?", "## Examples"] # Project Name、## Examples 失败({MD043:+1})

从中可以归纳出三个关键行为规则:

  1. 位置无关性:"?"" 放在列表开头、中间还是末尾,语义一致——它都要求"恰好有一个标题占据该槽位",不关心该标题的具体文本;
  2. 数量约束:"?"" 表示"恰好一个"(exactly one),与 "*"(零个或多个)和 "+"(一个或多个)形成量词上的区别。当槽位没有标题可填(如 question-extra 中 ## Examples 缺失)时,会触发 MD043 错误;
  3. 后置校验:规则在匹配完所有标题后,还会检查是否存在"多余"的期望项(lib/md043.mjs):
const extraHeadings = requiredHeadings.length - i;
if (
  !hasError &&
  ((extraHeadings > 1) ||
    ((extraHeadings === 1) && (requiredHeadings[i] !== "*"))) &&
  (anyHeadings || !requiredHeadings.every((heading) => heading === "*"))
) {
  addErrorContext(onError, params.lines.length, requiredHeadings[i]);
}

这段逻辑的深意在于:只有剩余期望项恰好为 1 且该项是 "*" 时才允许"缺标题";否则若仍有未匹配的必需标题(包括 "?""、普通字符串或 "+"),就会在文件最后一行位置报告错误。这解释了 question-extra 与 question-missing 的失败原因。

五、配置方式一:行内配置注释(markdownlint-configure-file)

关联测试文件采用的方式是行内配置,语法为 HTML 注释包裹的 JSON 片段:

<!-- markdownlint-configure-file {
  "required-headings": {
    "headings": [
      "# Project Name",
      "## Description",
      "?"
    ]
  }
} -->

使用要点:

  • 注释内必须使用规则的别名 required-headings(而不是编号 MD043)作为配置键;
  • 配置值是与外部配置完全同构的 JSON 对象,因此 headings 与 match_case 两个参数都可在此设置;
  • 该指令仅作用于当前文件,适合"单个文件自定义结构"或"测试用例自带期望配置"的场景;
  • 仓库中同类用法非常普遍,例如 test/required-headings-match-case.md、test/required-headings-zero-or-more.md 等均以此方式注入配置。

如果需要在命令行中禁止行内配置生效,可以传入 noInlineConfig: true(参见 test/markdownlint-test.mjs 中 readmeHeadings 测试的用法),此时仅外部配置生效。

六、配置方式二:外部配置文件与组合应用

对于需要为整组文档统一标题结构的场景,更常见的做法是把 MD043 配置写入项目级配置文件(如 .markdownlint.json 或 .markdownlint.yaml),例如:

{
  "MD043": {
    "headings": [
      "# Project Name",
      "## Description",
      "## Examples"
    ],
    "match_case": false
  }
}

仓库自身体现了这一最佳实践:测试 test/markdownlint-test.mjs 中的 readmeHeadings 用例,就用一段包含 "# markdownlint"、"## Install"、"## Overview"、"### Related" 等十余个条目的完整 MD043.headings 列表去校验项目 README 的标题结构,确保文档大纲与团队约定保持一致。这说明 MD043 完全可用于"CI 中校验文档结构是否符合规范"的工程化场景。

组合使用建议:

  • 同时开启 MD022(标题前后空行)、MD041(首行一级标题)等 headings 家族规则,可构建更完整的文档结构约束;
  • 使用 "*"(零或多个未指定标题)允许可选小节:例如 ["# Heading", "## Item", "*", "## Foot", "*"] 对应"允许 ### Detail、### Notes 等任意可选小节"的结构(见 doc/md043.md 示例);
  • 使用 "+"(一个或多个未指定标题)要求小节不可为空,例如 test/required-headings-one-or-more.md 中 ["# One", "+", "### Three", ...] 的配置。

七、通配符速查表与常见误区

特殊值 含义 匹配标题数 典型用途
"?"" exactly one unspecified heading 恰好 1 个 项目名、版本号等"内容可变但必须存在"的标题
"*" zero or more unspecified headings 0 个或多个 允许可选小节存在与否
"+" one or more unspecified headings 至少 1 个 强制某区间内必须出现小节

常见误区提醒:

  1. "?"" 不等于 "*":"?"" 要求槽位必须被一个标题填满,"*" 允许跳过。文档末尾用 "?"" 时,如果文档少写了最后一个标题,仍会报错(question-extra 即此场景);
  2. "?"" 不参与大小写比较:它直接跳过文本比对,因此无论实际标题是 # Project Name 还是 # project name 均可匹配;而普通字符串期望受 match_case 控制;
  3. headings 参数统一使用 ATX 风格书写(如 "## Text"),但文档本身可使用任意标题风格。规则实现通过 helpers/micromark-helpers.cjs 的 getHeadingLevel 将 setext 标题(===/---)折算为对应层级,因此 setext 与 ATX 混用不影响匹配;
  4. 错误行号语义:MD043 检测到错误时,报告第一个出问题标题的行号;若无标题可匹配时,报告文件最后一行行号(见 doc/md043.md 说明)。

八、如何验证本文所述行为

仓库提供了两条可复现的验证路径:

  1. 运行官方测试套件:通过 Node.js 运行 test/markdownlint-test.mjs,其中包含对 required-headings-question-* 系列文件的快照校验(test/markdownlint-test-scenarios.mjs.snapshot 保存了期望结果);
  2. 手工 lint 单个文件:使用 test/harness.mjs 对目标文件执行 lint 并打印结构化结果:
node test/harness.mjs test/required-headings-question-last.md
node test/harness.mjs test/required-headings-question-extra.md

对前者应得到无 MD043 错误的输出,对后者应看到在文件最后一行附近产生一条 required-headings(MD043)错误记录,与文件内 {MD043:+1} 的期望标记一致。通过修改 headings 数组中的 "?"" 位置并重新执行,即可直观验证"位置无关、数量唯一"的语义结论。

综上所述,"?"" 通配符为 markdownlint 的标题结构校验提供了"内容可变但结构必达"的精确表达力;理解它在 lib/md043.mjs 中的实现逻辑与 test/required-headings-question-last.md 等测试用例的验证方式,是高效配置 MD043、落地团队文档规范的关键一步。

登录后查看全文
markdownlint