markdownlint MD039 规则详解:链接文本中的空格检测与自动修复

原创2026-10-15 09:00:181,691 阅读
文章标签:开发工具Lint静态分析代码质量

markdownlint MD039 规则详解:链接文本中的空格检测与自动修复

本文围绕 markdownlint 规则 MD039(Spaces inside link text,别名 no-space-in-links),结合仓库中的规则文档、规则源码与场景测试用例展开,系统讲解该规则的触发条件、检测原理、自动修复能力、参考式链接等边界场景,以及在实际文档工程中如何配置与落地。

规则概览:MD039 是什么

MD039 是 markdownlint 内置规则之一,用于检测链接文本两侧出现多余空格的写法。官方文档将其归入 links 与 whitespace 两个标签,并提供别名 no-space-in-links,便于在配置文件或命令行中以更可读的方式引用。

规则的核心判定非常简单:链接文本(即 [ 与 ] 之间的内容)前后不应紧贴空格。以下写法会被 MD039 判定为违规:

[ a link ](https://www.example.com/)

修正方式是移除链接文本两侧的空格:

[a link](https://www.example.com/)

规则文档给出的 Rationale(设计理由)是:一致的格式排版能让文档更易于理解。从工程实践看,链接文本两侧的冗余空格还会导致链接显示文本与作者意图不符、破坏无障碍阅读体验,并干扰依赖文本内容的自动化工具,因此值得纳入 lint 检查。

触发条件详解:哪些写法会被判定为违规

依据规则文档与测试用例(第 17~31 行),MD039 会在以下几种形态下触发:

写法 触发情况
[ ](https://bar/) 触发:链接文本为空但含空格
[foo ](https://bar/) 触发:尾部多余空格
[ foo](https://bar/) 触发:头部多余空格
[ foo ](https://bar/) 触发:头部与尾部各有一处违规
[ "foo" ](https://bar/) 触发:引号包裹文本两侧带空格
[ \foo` ](https://bar/)` 触发:行内代码文本两侧带空格
[ *foo* ](https://bar/) 触发:斜体文本两侧带空格
[ __foo__ ](https://bar/) 触发:加粗文本两侧带空格

需要特别说明的是,空格的位置在链接文本的开头或结尾各计一次违规。例如 [ foo ](https://bar/) 会同时报告两条 MD039 错误:一条针对行首空格,一条针对行尾空格。这一点在快照(snapshot)测试中清晰可见:第 23 行 [ foo ] 同时生成了两条 errorRange 分别为 [2,1] 与 [6,1] 的错误记录。

合法写法:这些不会被误报

同样是带引号、行内代码或强调样式的链接文本,只要两侧没有空格,就不会触发 MD039。测试用例第 3~15 行验证了以下合法形态:

[](http://bar/)                        <!-- 空链接文本,无空格,合法 -->
[foo](https://bar/)                    <!-- 普通文本 -->
["foo"](https://bar/)                  <!-- 引号包裹 -->
[`foo`](https://bar/)                  <!-- 行内代码 -->
[*foo*](https://bar/)                  <!-- 斜体 -->
[__foo__](https://bar/)                <!-- 加粗 -->
[foo "bar"](https://baz/)              <!-- 链接文本内含空格但不在两侧 -->

最后一行 [foo "bar"](https://baz/) 尤其值得注意:MD039 只关注链接文本首尾两侧的空格,不检查文本内部出现的空格。

关键边界:哪些写法会被明确豁免

测试用例第 33~45 行还验证了两种容易误报的场景,理解它们有助于在阅读 lint 报告时减少困惑:

  1. 嵌套图片链接:Screenshot.png 这种「图片套链接」的经典写法不会被误报。因为图片属于链接文本内部的合法子节点,而非链接文本两侧的空格问题。
  2. 代码块中的正则表达式:测试文件第 36~45 行故意在代码块中放入形如 input.replace(/- /g, "one") 的 JavaScript 正则。MD039 检测的是 Micromark 解析出的 link 节点(即真实链接),代码块内容不会被解析成链接,因此不会触发 MD039——即使正则表达式中的 [- ] 看起来很像「空格 + 中括号」的组合。这两组用例正是为了守护该规则「绝不误报代码块」的行为底线。

源码级原理:MD039 如何实现

MD039 的实现位于规则源码。与 markdownlint 中一部分基于正则、面向行的传统规则不同,MD039 声明了 "parser": "micromark",即基于 Micromark 语法树(token 流)进行结构化检测。

检测主流程

核心逻辑在 MD039 函数中(lib/md039.mjs):

function MD039(params, onError) {
  const labels = filterByTypesCached([ "label" ])
    .filter((label) => label.parent?.type === "link");
  for (const label of labels) {
    const labelTexts = label.children.filter((child) => child.type === "labelText");
    for (const labelText of labelTexts) {
      if (labelText.text.trimStart().length !== labelText.text.length) {
        addLabelSpaceError(onError, label, labelText, true);
      }
      if (labelText.text.trimEnd().length !== labelText.text.length) {
        addLabelSpaceError(onError, label, labelText, false);
      }
    }
  }
}

执行流程分三步:

  1. 筛选链接标签:通过 filterByTypesCached(<a href="https://link.gitcode.com/i/1c88fee99df93f13acc21feaf8a7913c" target="_blank"> "label" ]) 取出全部 label token(该函数在 [lib/cache.mjs 中定义,会对解析结果做缓存以提升多次调用性能),再过滤出 parent.type === "link" 的节点,确保只处理真正的链接,而把 [text] 这类非链接的中括号文本排除在外(对应测试第 105 行「Not a link, just [ text in ] brackets」不报错的行为)。
  2. 遍历 labelText:对每个 label 下的 labelText 子节点,分别用 trimStart() 与 trimEnd() 判断文本开头/结尾是否有多余空白。
  3. 报告错误:任一侧存在空白即调用 addLabelSpaceError 上报。

错误定位与自动修复信息

addLabelSpaceError 函数(lib/md039.mjs)负责计算精确的错误位置与修复信息:

  • 通过正则 /^[^\S\r\n]+/(开头)与 /[^\S\r\n]+$/(结尾)定位空白字符的实际列范围,生成 errorRange(列号 + 长度);
  • 通过 addErrorContext(定义于 helpers/helpers.cjs)构造带上下文截断的错误对象,上下文为 label.text.replace(/\s+/g, " "),将 label 内部换行统一折叠成单个空格展示;
  • 同时输出 fixInfo(editColumn + deleteCount),供 applyFixes 工具做自动修复。

这正是 MD039 在规则文档中被标注为 Fixable(可修复) 的原因,该规则名也出现在可修复规则清单中。

多行链接文本的特殊行为

测试用例第 57~75 行专门覆盖了链接文本跨越多行(Wrapped 形态)的场景,这里的行为比单行情况更精细:

  • 换行发生在链接文本内部时,换行符本身不构成违规,只有 [ 后紧跟空格或 ] 前残留空格才会触发 MD039;
  • 若空格所在行本身是行尾(例如第 60 行的 link with leading space 末尾),会同时触发 MD009(no-trailing-spaces)与 MD039 两条规则——快照中第 60、63、69、74 行均出现 MD009 与 MD039 并存、且 MD009 的修复信息(删除行尾空格)与 MD039 的修复信息(删除链接文本两侧空格)作用于同一位置的组合;
  • 快照还显示,部分多行场景(第 58、63、74 行)MD039 的 fixInfo 为 null,说明并非所有违规都提供自动修复,工具只对能精确定位且安全删除的空格给出修复建议。

参考式链接与快捷引用:检测范围延伸

MD039 不仅作用于内联式链接 text,同样覆盖参考式链接(reference-style links)与快捷引用(shortcut references)。测试用例第 77~103 行完整验证了这一范围:

写法 说明
[][ref]、[link][ref] 参考式链接,无空格,合法
[link ][ref]、[ link][ref] 参考式链接,文本两侧带空格,违规
[ link ][ref] 两侧各计一次违规
[ref]、[ref][] 快捷引用/折叠引用,无空格,合法
[ref ]、[ ref]、[ ref ] 快捷引用文本两侧带空格,违规

第 103 行 [ref]: https://example.com 是参考式链接的定义行,供上述用例解析使用。从实现上看,MD039 并不关心链接是内联还是参考式——它只检查 Micromark 语法树中的 link 节点,因此任何形式的链接只要文本两侧带空格都会被一致地检出。

如何运行与验证

使用 markdownlint 检查

在仓库中,可以通过以下命令对单个 Markdown 文件执行 lint(markdownlint 提供了 promise 风格的异步 API,见 test/harness.mjs 的调用示例):

npx markdownlint test/spaces_inside_link_text.md

执行后,MD039 的报告会包含:

  • ruleNames:["MD039", "no-space-in-links"];
  • ruleDescription:Spaces inside link text;
  • errorContext:如 "[ foo]"、"[- ]" 等被折叠后的链接文本片段;
  • errorRange:违规空格的精确列位置;
  • fixInfo:可修复时的 editColumn / deleteCount;
  • severity:error。

场景测试如何验证规则行为

仓库的场景测试会遍历 test/ 目录下所有 .md 文件,按行内 {MD039} 标记断言错误行号,并校验「修复后是否仍有残留错误」。其机制(test/markdownlint-test-scenarios.mjs)可归纳为:

  1. 用正则 /\{(MD\d+)(?::([-+]?)(\d+))?\}/g 解析测试文件中 {MD039} 这类标记,{MD039:-1} 表示「上一行」(- 减 1 行),{MD039:2} 表示「第 2 行」,从而在不引入额外断言代码的前提下标注期望的错误位置;
  2. 对文件执行 lint,比对实际错误行号与标记行号是否一致;
  3. 用 applyFixes 应用所有可修复错误后再次 lint,断言修复后的文件不再残留可修复错误。

例如测试文件第 17 行 [ ](https://bar/) {MD039} 的标记,与快照中第 17 行两条 MD039 错误(errorRange 分别为 [2,1] 与 [2,1])完全对应,其中一条对应 [ 后的空格、另一条对应 ] 前的空格。

配置与协作:将 MD039 接入文档工程

MD039 默认启用且属于常见基线规则(markdownlint 的默认配置即包含该规则)。在实际项目中可按需调整:

  • 禁用规则:在 .markdownlint.json 中设置 "MD039": false;
  • 按行豁免:在违规行上方添加 <!-- markdownlint-disable MD039 --> 注释;
  • 配合相关规则:MD039 常与 MD009(no-trailing-spaces)一起出现(如本文多行示例所示),两者都关注空白字符的规范性;同时,链接文本语义层面可搭配 MD059(descriptive-link-text) 规则(lib/md059.mjs)使用,后者负责检查链接文本是否具有描述性(如禁止 "click here" 等空泛文本),二者一个管格式、一个管语义,可共同提升链接质量。

需要留意的是,测试文件末尾的 HTML 注释:

<!-- markdownlint-configure-file {
  "descriptive-link-text": false
} -->

这是 markdownlint 支持的内联配置语法,用于在测试文件中单独关闭 MD059,避免「链接文本含空格」的用例同时被语义规则干扰——这说明在编写包含格式违规样例的文档时,可以用同类内联配置精确控制规则集合,保证 lint 结果聚焦于被测规则本身。

小结

MD039 是一条小而精的空白规范规则:它基于 Micromark 语法树精准识别链接文本两侧的空格,覆盖内联、参考式与快捷引用等多种链接形态,支持自动修复,并对代码块、嵌套图片等边界场景做了严格豁免。对于维护大规模 Markdown 文档的团队,将 MD039 纳入 CI 检查并配合 applyFixes 自动修复,是保持链接排版一致、提升文档可读性的低成本高收益手段。若需深入研究,可继续阅读规则实现、规则文档与完整场景用例。

登录后查看全文
markdownlint