markdownlint 规则实战：用 MD044/proper-names 强制统一专有名词大小写-北京尧图网络

开发工具代码质量Lint静态分析【免费下载链接】markdownlintA Node.js style checker and lint tool for Markdown/CommonMark files.项目地址https://gitcode.com/gh_mirrors/ma/markdownlint点击查看免费下载本篇文章围绕 markdownlint 仓库中的测试用例 test/proper-names-alternate.md 展开系统讲解内置规则MD044别名proper-names的检测机制、参数配置、匹配边界原理与自动修复能力。读完本文你将能够用 markdownlint 为项目文档建立统一的专有名词大小写规范例如强制markdownlint、Node.js、.NET的拼写并理解该规则在引号、强调、独立成行、URL 等不同上下文中的行为差异。MD044 规则是什么MD044是 markdownlint 内置规则之一规则描述为 Proper names should have the correct capitalization专有名词应使用正确的大小写官方文档见 doc/md044.md。其用途是当文档中出现与names数组中配置的拼写不一致的写法时上报违规从而为项目名、产品名等专有名词强制统一的字母大小写。该规则包含三个可配置参数参数类型默认值说明code_blocksbooleantrue是否检查代码块与行内代码code span中的内容html_elementsbooleantrue是否检查 HTML 元素与属性中的内容namesstring[][]专有名词列表按期望的正确大小写书写例如要强制 JavaScript 的正确拼写可将names配置为[ JavaScript ]有些专有名词在不同语境下大小写不同例如 GitHub 与域名 github.com此时应把两种形态都加入names数组[ GitHub, github.com ]把code_blocks设为false可跳过代码块与代码 span把html_elements设为false可跳过 HTML 元素及属性例如用专有名词作为a/href或img/src路径的一部分时。测试文件 proper-names-alternate.md 场景拆解test/proper-names-alternate.md 是专门为MD044设计的详细结果测试用例标题即 Detailed Results Proper Names。该文件以四种上下文反复验证三个专有名词markdownlint、Node.js、.NET的检测1. 纯文本中的违规检测Text Markdownlint text. {MD044} Text node.JS text. {MD044} Text .net text. {MD044} Text example.net text. {MD044}{MD044}是 markdownlint 测试文件中标注预期违规的约定记号。这四行分别演示Markdownlint与正确拼写markdownlint不符node.JS与Node.js不符大小写错位而非整体大写.net与.NET不符example.net中的.net也会被命中原因见下文匹配边界的特殊处理。根据对应测试快照 test/markdownlint-test-scenarios.mjs.snapshotproper-names-alternate.md 1用例第 3 行的报错详情为{ lineNumber: 3, ruleNames: [ MD044, proper-names ], errorDetail: Expected: markdownlint; Actual: Markdownlint, errorRange: [ 6, 12 ], fixInfo: { editColumn: 6, deleteCount: 12, insertText: markdownlint } }errorDetail以 Expected: xxx; Actual: yyy 的形式给出期望与实际的对照errorRange标出命中位置起始列长度fixInfo则给出自动修复所需的编辑信息。2. 引号包裹的内容Text Markdownlint text. {MD044} Text node.JS text. {MD044} Text .net text. {MD044} Text example.net text. {MD044}被双引号包裹的文本同样会被扫描说明该规则基于底层解析出的data类型 token 检查不受引号影响。3. 强调emphasis包裹的内容Text **Markdownlint** text. {MD044} Text **node.JS** text. {MD044} Text **.net** text. {MD044} Text **example.net** text. {MD044}被**加粗的文本同样会被命中。从源码角度解释MD044 扫描的是 micromark 解析出的data类型 token 文本见 lib/md044.mjs 中的scannedTypes而强调标记本身不改变内部文本的data属性因此无论是否加粗匹配逻辑一致。4. 独立成行的违规检测Markdownlint {MD044} node.JS {MD044} .net {MD044} example.net {MD044}当专有名词作为整行内容时列位置从第 1 列开始命中快照中errorRange的起始列为 1进一步验证该规则对行首位置的覆盖。5. 行内配置测试文件的灵魂测试文件末尾通过 markdownlint 行内配置语法定义本次测试的names列表!-- markdownlint-configure-file { proper-names: { names: [ markdownlint, Node.js, .NET ] } } --这是 markdownlint 的整文件级行内配置语法markdownlint-configure-file其内容为 JSON对整个文件生效位置不限。语法说明见 README.md。该配置也可以写成多行形式!-- markdownlint-configure-file { proper-names: { names: [ markdownlint, Node.js, .NET ] }, no-trailing-spaces: false } --注意names只包含markdownlint、Node.js、.NET三个词而文件中刻意放入了未配置的example.net——它依然会命中被当作.NET的错误写法这正是该测试文件要验证的特殊边界场景。源码实现匹配与排除的逻辑细节MD044的实现位于 lib/md044.mjs整体流程可以拆解为四步第一步预处理 names 列表。对names做类型兜底非数组视为空数组并按名称长度降序排序同长度再按 localeCompare。这样长名称优先匹配避免短名称抢先占用文本位置L18-L24。第二步确定扫描范围。规则使用micromark解析器默认扫描data类型 token当code_blocks为true时追加codeFlowValue与codeTextData当html_elements为true时追加htmlFlowData与htmlTextDataL31-L39。同时通过ignoredChildTypes集合codeFencedFence、definition、reference、resource跳过子 token从而避免对链接定义、引用、资源等内容重复计数。第三步构造匹配正则并扫描。这是本规则最核心的实现细节lib/md044.mjsconst startNamePattern /^\W/.test(name) ? : \\b_*; const endNamePattern /\W$/.test(name) ? : _*\\b; const namePattern (${startNamePattern})(${escapedName})${endNamePattern}; const nameRe new RegExp(namePattern, gi);即若名称以非单词字符开头如.NET的开头是.则不要求词边界\b只允许可选的强调下划线_*若名称以非单词字符结尾同理。这正是example.net被命中的原因——.net内嵌于example.net时匹配模式不要求.之前存在词边界因此整个子串被判定为错误拼写并产生修复建议把.net替换为.NET得到example.NET。第四步排除自动链接并上报。对命中的名称范围做两层排除一是同一次扫描中已命中过的名称范围exclusions数组去重避免同一位置重复上报二是对每个 token 重新解析出literalAutolink类型的范围若命中范围与自动链接重叠则跳过lib/md044.mjs——这就是proper-names-links.md与proper-names-urls.md中https://example.com/javascript/about等 URL 内部不会被误报的原理。最后通过addErrorDetailIf上报并附带editColumn/deleteCount/insertText形式的fixInfoL89-L102。如何运行与验证仓库中的 test/harness.mjs 是一个可直接运行的测试驱动脚本它接收文件路径作为参数内部调用markdownlint/promise的lint输出完整结果node test/harness.mjs test/proper-names-alternate.md输出为包含errors数组与fixed文本的对象。将输出与 test/markdownlint-test-scenarios.mjs.snapshot 中的proper-names-alternate.md 1快照对照即可确认每个违规的行号、errorDetailExpected/Actual 对照、errorRange与fixInfo均与预期一致。快照中fixed字段还展示了自动修复后的完整文本所有Markdownlint变为markdownlint、node.JS变为Node.js、.net变为.NET而example.net变为example.NET。更多边界场景同名系列测试仓库在test/目录下为MD044准备了完整的场景矩阵可与proper-names-alternate.md对照阅读test/proper-names.md主测试文件覆盖引号、强调、列表、块引用、代码块、HTML、链接、图片、裸 URL、前端元数据front matter等全部上下文test/proper-names-no-code.mdcode_blocks: false时代码块与代码 span 内的javascript不再报错test/proper-names-no-html.mdhtml_elements: false时HTML 元素与属性中的命中被跳过test/proper-names-substrings.md验证aws-control-tower、aws-vault、AWS这类带前缀/连字符的名称互不干扰test/proper-names-non-word-boundaries.md专门验证.NET、NET.等以非单词字符开头/结尾的名称对词边界的处理与上文源码第三步呼应test/proper-names-links.md 与 test/proper-names-urls.md验证 URL、自动链接、链接文本与链接引用定义内的排除逻辑test/proper-names-projects.md以github.com/about、github.com、vue-router、npm等项目名为例演示同一名称多个形态的配置方式。在真实项目中使用配置与自动修复通过行内注释配置在需要约束的 Markdown 文件开头或任意位置加入!-- markdownlint-configure-file { proper-names: { names: [ markdownlint, Node.js, .NET, JavaScript, GitHub ], code_blocks: false } } --该配置对整个文件生效若存在多个markdownlint-configure-file注释则按从上到下的顺序合并应用。内容默认按 JSON 解析也可通过options.configParsers支持其他格式见 README.md。在配置文件或 API 中使用在项目级配置文件中同样以proper-names作为键名配置{ MD044: { names: [ JavaScript, GitHub, npm ], html_elements: false } }自动修复MD044属于可修复规则文档中标注 Fixable: Some violations can be fixed by tooling每条违规的fixInfo都带有insertText即正确拼写。在代码中可以通过applyFixes批量应用修复import { applyFixes } from markdownlint; import { lint as lintSync } from markdownlint/sync; const results lintSync({ strings: { content: original } }); const fixed applyFixes(original, results.content);这正是测试快照中fixed字段的产生方式README.md。命令行工具如 markdownlint-cli2也会利用fixInfo提供--fix类能力将文档中所有专有名词的大小写一键纠正。小结MD044/proper-names通过配置化的names列表为文档中的项目名、产品名建立可强制的大小写规范。理解其源码中的匹配边界逻辑以非单词字符开头/结尾的名称不受词边界约束与自动链接排除机制可以准确预判哪些位置会被命中、哪些 URL 会被豁免从而在真实项目中配置出既不误报也不漏报的专有名词检查策略。建议结合 doc/md044.md 规则文档、lib/md044.mjs 实现以及test/目录下的同名测试系列进行系统性验证。赞分享开发工具代码质量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静态分析上一篇10分钟解决90%的Linux卡顿系统性能调优终极指南下一篇Sails 扩展机制完全指南Generators、Adapters 与 Hooks 三大扩展点详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

markdownlint 规则实战：用 MD044/proper-names 强制统一专有名词大小写

相关推荐

GLSL 精度限定符 lowp 完全指南：The Book of Shaders 中的精度体系与实践

纯 Python 井字棋游戏引擎库（tic-tac-toe library）安装与打包实战指南

Olares 多用户与团队成员管理实战指南：创建账户、角色权限与资源配额全解析

更多资讯

各类继电器接线详解：线圈与触点、接线图与避坑指南

MCU与MATLAB串口通信帧格式设计：协议、状态机与联调实战

QQ邮箱网页版下载无法改保存路径？根因与浏览器设置有关

ES查询入门：URI Search与Query DSL对比解析

《派出你的AI同事：WorkBuddy案例实战》042：私有化部署落地

Windows 激活与 Office 激活完整指南：MAS 一键免费激活，3 分钟拿到永久授权

今日更新

Cephadm实战指南：Linux系统工程师的生产级Ceph集群部署与排障

不想再被 Token 额度卡脖子？把免费 API 接入 WorkBuddy 的完整教程

ITK中SpatialObject几何体系解析：坐标系、变换与管道集成

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？