markdownlint MD044（proper-names）规则实战：URL 场景下的专有名词大小写检查与测试样本解读

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

导读

在技术文档中，"JavaScript" 被写成 "Javascript"、"GitHub" 被写成 "Github" 是常见的拼写错误，而 markdownlint 的MD044（别名proper-names）规则正是用来强制专有名词大小写一致性的检查器。本文以仓库中的专项测试样本 test/proper-names-urls.md 为骨架，系统剖析该规则在 URL 场景下"该报错就报错、该豁免就豁免"的完整行为边界：普通文本中的小写专有名词如何被标记，裸 URL、自动链接、Markdown 链接、行内代码、代码块中的 URL 为何被整体豁免，以及 HTML 注释内容为何仍会被扫描。读完本文，你将掌握 MD044 的配置参数、源码级匹配原理与自动修复机制，并能在真实项目中直接落地使用。

一、规则概览：MD044 / proper-names 是什么

MD044的正式名称是Proper names should have the correct capitalization，归属spelling（拼写）标签，别名proper-names。其官方规则说明位于 doc/md044.md（同步收录于 doc/Rules.md 的 MD044 一节），核心语义是：当names数组中的任一字符串在文档中未按指定大小写出现时，触发违规。它常被用于统一项目名、产品名的写法。

规则共接受三个参数：

该规则被标记为Fixable: Some violations can be fixed by tooling，即部分违规可由工具自动修复（applyFixes直接改写出正确大小写）。

典型配置方式有两种。第一种是官方文档示例，将标准写法放入names：

[ "JavaScript" ]

第二种是处理"同一名称在不同上下文大小写不同"的情况，把两种形式都加进数组：

[ "GitHub", "github.com" ]

相关行为在 test/proper-names.md 中有完整演示：Markdownlint、Javascript、NPM、Github均被标记为违规，而JavaScript、Node.js、npm、GitHub通过；注意Node.JSX、nodesjs、NPMI等包含子串但整体不是专有名词的写法不会被误报。

二、测试样本的整体设计：为什么单独为 URL 建一个文件

test/proper-names-urls.md 是围绕"专有名词出现在 URL 中"这一特殊场景构建的专项测试文件。它之所以值得单独成文研究，是因为 URL 天然由小写字母组成（如https://example.com/directory/file），如果 MD044 对 URL 内部文本逐一检查，任何小写专有名词都会引发海量误报。因此规则实现必须解决一个核心矛盾：既要在正文文本中揪出错误大小写的专有名词，又要整体放过 URL 中的同类字符串。

整个样本被刻意分成三段，形成"报错—豁免—再报错"的对照结构：

1. 前段（第 3–8 行）：独立的普通单词https、example、com、directory、file，验证"不在 URL 中时，小写专有名词会被报错"；
2. 中段（第 12–51 行）：同一批单词拼成的完整 URL，以裸 URL、尖括号自动链接、Markdown 链接、行内代码、围栏代码块、缩进代码块、带点文件名、%20编码等多种形态出现，验证"在 URL 中时全部豁免"；
3. 尾段（第 53–68 行）：{MD044:+2}标记与markdownlint-configure-fileHTML 注释内嵌配置，验证"HTML 注释内容仍会被扫描"这一边界，并为整个文件提供规则配置。

样本还通过块引用注明The following lines are deliberately duplicated（以下行是刻意重复的），说明中段大量成对出现的重复行是有意为之，用于检验规则在相同内容重复出现时输出的稳定性与去重逻辑（同一 token 文本被多次匹配时的排除机制）。

三、前段对照：普通文本中的小写专有名词被逐一标记

测试样本开头的五行使独立的专有名词以全小写形式出现在普通段落文本中：

Text https text {MD044} Text example text {MD044} Text com text {MD044} Text directory text {MD044} Text file text {MD044} Text HTTPS EXAMPLE COM DIRECTORY FILE text

对照测试快照 test/markdownlint-test-scenarios.mjs.snapshot 中proper-names-urls.md的预期结果，前五行各产生一条MD044违规，且每条的列信息与修复建议都精确到字符：

注意第 8 行Text HTTPS EXAMPLE COM DIRECTORY FILE text没有标注{MD044}，因为五个专有名词都以正确的大写形式出现，规则放行。这组对照清晰说明：一旦某个词不以names数组中的规定大小写出现，无论它是 URL 的组成部分（https、example、com）还是路径段（directory、file），在普通正文中都会被当作拼写错误报出。

四、中段核心行为：各类 URL 形态被整体豁免

中段用同一批词汇拼出完整 URLhttps://example.com/directory/file，验证规则对 URL 的豁免行为。测试样本中的每一种形态，快照均确认零违规：

• 裸 URL：Text https://example.com/directory/file text（第 12–13 行，成对重复）
• 尖括号自动链接：Text <https://example.com/directory/file> text（第 16–17 行）
• Markdown 链接（文本与目标均为 URL）：Text [https://example.com/directory/file](https://example.com/directory/file) text（第 20–21 行）
• 行内代码：Text `https://example.com/directory/file` text（第 24–25 行）
• 围栏代码块（```text，第 27–30 行）：块内两行 URL 均不报错
• 缩进代码块（第 32–33 行，4 空格缩进）：同样豁免

随后是带变体的 URL：

• https://example.com/directory/text.file（文件名含点，第 35–36 行）
• https://example.com/directory/text%20text.file（%20编码空格，第 38–39 行）
• 尖括号包裹的上述两种（第 41–45 行）
• Markdown 链接包裹的上述两种（第 47–51 行）

所有这些 URL 中，https、example、com、directory、file全部小写，却没有任何一条被标记。这组测试从实现层面传达了一条重要规则：专有名词豁免的判定对象是"完整的 URL"，而不是单词本身。text.file文件名中的file、%20之后的text，只要整体构成了合法的自动链接（literalAutolink），其内部文本就整体不参与检查。

这与前段第 3–7 行的行为形成鲜明对照：单独出现https时它不是 URL（缺少//与域名部分），因而被检查；一旦拼成完整的https://example.com/directory/file，Micromark 解析器将其识别为自动链接，规则便整体放行。

五、中段边界细节：重复行、文件名与编码

中段的"刻意重复"不是冗余，而是测试设计的一部分：第 12/13 行、第 16/17 行、第 20/21 行、第 24/25 行、第 27–33 行代码块内两行、第 35–51 行各变体均成对出现。其检验目标是规则的稳定性与幂等性——同一 token 文本被正则多次命中时，exclusions（排除区间）机制必须保证后续匹配不会重复报错，也不会互相干扰。此外，带点文件名（text.file）与%20编码（text%20text.file）验证了 URL 豁免并不依赖简单的字母/数字正则，而是依赖解析器对 URL 边界的权威判定：即使 URL 内部出现点号、空格编码、路径段，豁免依然生效。

六、尾段边界：HTML 注释内容仍被扫描，内嵌配置如何生效

测试样本第 53 行出现的{MD044:+2}是测试框架中的"行号偏移标记"。按 test/markdownlint-test-scenarios.mjs 中标记解析逻辑，{MD044:+2}表示"第 53 行向后偏移 2 行"，即断言第 55 行存在一条 MD044 违规。第 55 行正是：

<!-- markdownlint-configure-file {

对照快照，第 55 行的违规细节为：Expected: FILE; Actual: file，违规区间第 29 列起 4 个字符。原因在于markdownlint-configure-file这个注释中的file是 HTML 注释文本的一部分，而html_elements参数默认值为true，HTML 注释内容属于被扫描的htmlFlowData文本范围，且file不在ignoredChildTypes排除清单中——因此注释文本中的小写file照样触发 MD044。快照的fixed输出也印证了这一点，修复后的文件第一行注释被改写为：

<!-- markdownlint-configure-FILE {

这是一个非常值得注意的工程细节：即使专有名词出现在 HTML 注释（包括 markdownlint 自身的内嵌配置注释）里，只要html_elements未关闭，就会被检查。因此在真实项目中若在注释里使用了专有名词的小写形式，需要把正确写法加入names，或将html_elements设为false。

第 55–68 行同时是整份测试文件的配置源头，使用markdownlint-configure-fileHTML 注释内嵌 JSON 配置：

{ "proper-names": { "names": [ "DIRECTORY", "EXAMPLE", "HTTPS", "FILE", "COM" ] }, "line-length": false, "no-bare-urls": false, "code-block-style": false }

配置要点解读：

• names中五个词全部大写，这正是前段五条小写单词被标记的依据——它们违反了这五项规定写法；
• "no-bare-urls": false关闭了 MD034（裸 URL） 规则，否则第 12–15 行的裸 URL 会先被 MD034 标记，干扰 MD044 的对照观察；
• "line-length": false关闭 MD013 行长限制，避免长 URL 行产生干扰性违规；
• "code-block-style": false关闭 MD046 代码块风格一致性检查，避免缩进代码块与围栏代码块混用时报错，保证中段代码块测试行的纯粹性。

七、源码级实现原理：lib/md044.mjs 的匹配与豁免机制

MD044 的实现位于 lib/md044.mjs，基于 micromark 解析器（"parser": "micromark"）。其核心逻辑可拆解为四步：

第一步：准备专有名词列表。names先归一化为数组，然后按"名称长度降序、同长按字典序升序"排序（lib/md044.mjs）。长名称优先匹配，是为了保证aws-vault这类包含子串的复合名在遇到AWS时不会被错误拆分，test/proper-names-substrings.md 专门验证了这一行为。

第二步：构建大小写不敏感的正则。对每个名称先经escapeForRegExp（helpers/helpers.cjs）转义正则特殊字符，再拼接成(\b_*)(name)_*\b形式并加gi标志（lib/md044.mjs）。\b词边界与可选下划线保证了"整个单词匹配"：Javascript会命中JavaScript模板，而javascripts、Node.JSX、NPMI这类更长或更短的单词不会被误报。名称本身若以\W开头或结尾（如.NET、NET.），边界模式会被省略，test/proper-names-non-word-boundaries.md 对此有专门覆盖。

第三步：按配置选择扫描的 token 类型。默认扫描data文本；code_blocks为true时追加codeFlowValue（围栏/缩进代码块内容）与codeTextData（行内代码）；html_elements为true时追加htmlFlowData与htmlTextData（HTML 元素文本与属性，含注释内容）（lib/md044.mjs）。这就是第六节中 HTML 注释内容会被扫描的源码依据，也解释了 test/proper-names-no-code.md 里code_blocks: false时行内代码与代码块文本被放行的原因。

第四步：URL（literalAutolink）整体豁免。这是 URL 场景的核心机制。每当在某个 token 文本中命中一个名称匹配，规则会调用parse(token.text)对这段文本做二次解析，找出其中所有literalAutolink（自动链接，即裸 URL）token 的行列区间，加入exclusions排除列表（lib/md044.mjs）。随后用hasOverlap（helpers/helpers.cjs）判断"本次名称命中区间"是否与任一 URL 区间重叠——重叠即豁免，不报错。这解释了为何Text https://example.com/directory/file text整体放行：https、example、com、directory、file的命中区间全部落在同一个自动链接区间内。

同时，排除区间本身也会被记录（lib/md044.mjs），配合hasOverlap保证同一 URL 即使被多个名称命中（如https与example同时命中），也只会被计算一次、不会产生重复报错——这正是第五节所述"刻意重复行"所验证的稳定性。

八、测试框架如何验证：标记断言、快照与自动修复

整个样本由 test/markdownlint-test-scenarios.mjs 驱动验证。框架流程如下：

1. 读取测试文件并调用lint()检查；
2. 用正则/\{(MD\d+)(?::([-+]?)(\d+))?\}/g解析行内标记，{MD044}断言当前行有违规，{MD044:+2}断言偏移 2 行后有违规，{MD044:55}形式则直接指定行号（test/markdownlint-test-scenarios.mjs）；
3. 将实际违规行号与标记断言的期望行号逐一比对，断言Too few or too many issues found.；
4. 对全部违规调用applyFixes生成修复后的文本，与快照比对（t.assert.snapshot），并将完整结果沉淀到 test/markdownlint-test-scenarios.mjs.snapshot；
5. 对修复后的文本再次lint，确保不再残留带fixInfo的违规（即修复完备性）。

对proper-names-urls.md而言，快照确认该文件恰好产生 6 条 MD044 违规（第 3/4/5/6/7/55 行），中段全部 URL 形态零误报，修复后唯一被改写的内容是第 55 行注释中的file→FILE。这份快照既是测试样本行为的权威答案，也是读者复现实验时的对照基准。

九、真实项目落地：配置建议与注意事项

将 MD044 用于真实仓库时，可参考以下实践：

场景一：统一项目名与产品名写法。在.markdownlint.json等配置文件中声明：

{ "MD044": { "names": ["JavaScript", "Node.js", "GitHub", "npm", "markdownlint"] } }

场景二：专有名词以多种大小写形式出现。例如同时声明GitHub与github.com，或参考 test/proper-names.md 中同时声明multiplecase、mULTIPLEcASE、MultipleCase的做法，把所有合法形式都列入names。

场景三：URL 路径中混用大小写。若项目文档中大量出现形如https://example.com/MyProject/的 URL，且MyProject是专有名词，MD044 会因 URL 整体豁免而放行，不会误报；若希望 URL 中的路径段也被检查，可以针对链接文本（MyProject）中的非 URL 部分配置规则——链接文本中的专有名词不会被 URL 豁免，test/proper-names-links.md 对此有专门覆盖（该样本中链接文本javascript被标记，而https://example.com/javascript/about形式的链接目标与定义行均豁免）。

场景四：避免干扰相邻规则。当文档含有大量裸 URL 时，需同步配置no-bare-urls: false与line-length: false，否则 MD034 与 MD013 会先于 MD044 产生大量干扰性违规，正如测试样本的配置块所示。

场景五：代码与 HTML 内的名称。默认code_blocks: true、html_elements: true意味着代码、行内代码、HTML 元素与注释中的专有名词都会被检查（test/proper-names.md 中<script>内javascript、注释内javascript均被标记可证）。若这些区域确实需要保留特殊大小写，按 test/proper-names-no-code.md 的做法将code_blocks或html_elements设为false。

关于自动修复。每条违规都携带精确的fixInfo（editColumn、deleteCount、insertText），如快照所示：第 3 行违规的修复信息为editColumn: 6, deleteCount: 5, insertText: "HTTPS"。因此通过 markdownlint 的applyFixes或集成工具（如编辑器的 fix-on-save）即可一键将错误大小写替换为标准写法。需注意修复仅针对可自动确定的替换，若同一位置存在多种合法形式（names中同时声明GitHub与github.com），修复行为会以匹配到的具体名称形态为准。

总结

以 test/proper-names-urls.md 为窗口可以看到，markdownlint 的 MD044 规则在处理 URL 场景时遵循一条清晰的原则：专有名词的大小写检查以单词为粒度，以 URL 为豁免边界。普通文本中的https、example、file会被逐一标记并要求修正为HTTPS、EXAMPLE、FILE；而一旦它们构成合法的自动链接，则被 Micromark 解析器识别并整体豁免。源码中 lib/md044.mjs 的literalAutolink区间排除、exclusions去重与hasOverlap重叠判定，共同保证了这一行为在重复行、编码 URL、带点文件名等边界情况下依然稳定可靠。理解这套机制后，无论是配置规则、调试误报还是自定义扩展，你都能基于本文提供的源码与测试证据快速定位问题。

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