开发工具代码质量Lint静态分析【免费下载链接】markdownlintA Node.js style checker and lint tool for Markdown/CommonMark files.项目地址https://gitcode.com/gh_mirrors/ma/markdownlint点击查看免费下载导读在技术文档中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数组中的任一字符串在文档中未按指定大小写出现时触发违规。它常被用于统一项目名、产品名的写法。规则共接受三个参数参数类型默认值作用code_blocksbooleantrue是否检查代码块与行内代码code span中的文本html_elementsbooleantrue是否检查 HTML 元素与属性含注释内容中的文本namesstring[][]需要强制大小写的一组专有名词列表该规则被标记为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 中的同类字符串。整个样本被刻意分成三段形成报错—豁免—再报错的对照结构前段第 3–8 行独立的普通单词https、example、com、directory、file验证不在 URL 中时小写专有名词会被报错中段第 12–51 行同一批单词拼成的完整 URL以裸 URL、尖括号自动链接、Markdown 链接、行内代码、围栏代码块、缩进代码块、带点文件名、%20编码等多种形态出现验证在 URL 中时全部豁免尾段第 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违规且每条的列信息与修复建议都精确到字符行号原文预期Expected实际Actual违规列区间3Text https textHTTPShttps第 6 列起 5 个字符4Text example textEXAMPLEexample第 6 列起 7 个字符5Text com textCOMcom第 6 列起 3 个字符6Text directory textDIRECTORYdirectory第 6 列起 9 个字符7Text file textFILEfile第 6 列起 4 个字符注意第 8 行Text HTTPS EXAMPLE COM DIRECTORY FILE text没有标注{MD044}因为五个专有名词都以正确的大写形式出现规则放行。这组对照清晰说明一旦某个词不以names数组中的规定大小写出现无论它是 URL 的组成部分https、example、com还是路径段directory、file在普通正文中都会被当作拼写错误报出。四、中段核心行为各类 URL 形态被整体豁免中段用同一批词汇拼出完整 URLhttps://example.com/directory/file验证规则对 URL 的豁免行为。测试样本中的每一种形态快照均确认零违规裸 URLText https://example.com/directory/file text第 12–13 行成对重复尖括号自动链接Text https://example.com/directory/file text第 16–17 行Markdown 链接文本与目标均为 URLText [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 空格缩进同样豁免随后是带变体的 URLhttps://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/fileMicromark 解析器将其识别为自动链接规则便整体放行。五、中段边界细节重复行、文件名与编码中段的刻意重复不是冗余而是测试设计的一部分第 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参数默认值为trueHTML 注释内容属于被扫描的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 专门验证了这一行为。第二步构建大小写不敏感的正则。对每个名称先经escapeForRegExphelpers/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与htmlTextDataHTML 元素文本与属性含注释内容lib/md044.mjs。这就是第六节中 HTML 注释内容会被扫描的源码依据也解释了 test/proper-names-no-code.md 里code_blocks: false时行内代码与代码块文本被放行的原因。第四步URLliteralAutolink整体豁免。这是 URL 场景的核心机制。每当在某个 token 文本中命中一个名称匹配规则会调用parse(token.text)对这段文本做二次解析找出其中所有literalAutolink自动链接即裸 URLtoken 的行列区间加入exclusions排除列表lib/md044.mjs。随后用hasOverlaphelpers/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 驱动验证。框架流程如下读取测试文件并调用lint()检查用正则/\{(MD\d)(?::([-]?)(\d))?\}/g解析行内标记{MD044}断言当前行有违规{MD044:2}断言偏移 2 行后有违规{MD044:55}形式则直接指定行号test/markdownlint-test-scenarios.mjs将实际违规行号与标记断言的期望行号逐一比对断言Too few or too many issues found.对全部违规调用applyFixes生成修复后的文本与快照比对t.assert.snapshot并将完整结果沉淀到 test/markdownlint-test-scenarios.mjs.snapshot对修复后的文本再次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。关于自动修复。每条违规都携带精确的fixInfoeditColumn、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静态分析【免费下载链接】markdownlintA Node.js style checker and lint tool for Markdown/CommonMark files.项目地址https://gitcode.com/gh_mirrors/ma/markdownlint点击查看免费下载相关推荐markdownlint MD044 规则详解用 proper-names 强制专有名词的正确大小写markdownlint MD044 规则详解用 proper names 强制专有名词的正确大小写 markdownlint 的 MD044 别名 pro开发工具代码质量Lint静态分析remoteintech.company 公司档案解析以 Okta 全远程企业档案为例的字段规范与站点渲染链路remoteintech.company 公司档案解析以 Okta 全远程企业档案为例的字段规范与站点渲染链路 Okta 是社区维护的远程友好科技公司目录 r开发工具代码质量Lint静态分析markdownlint MD044 规则实战用 proper-names 精确控制专有名词大小写与 HTML 元素扫描范围markdownlint MD044 规则实战用 proper names 精确控制专有名词大小写与 HTML 元素扫描范围 导读 本篇文章围绕 markdo开发工具代码质量Lint静态分析上一篇PostHog Usage Metricssystem.usage_metrics模型全解析Customer Analytics 个人档案页的团队级指标定义与查询指南下一篇OMI 语音 Slack 消息发送实战omi-slack-app 插件的触发短语、分段收集、OAuth 集成与 Railway 部署全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考