★ FEATURED ARTICLE 开发工具代码质量Lint静态分析【免费下载链接】markdownlintA Node.js style checker and lint tool for Markdown/CommonMark files.项目地址https://gitcode.com/gh_mirrors/ma/markdownlint点击查看免费下载本文以 markdownlint 仓库中的 blanks-around-headings-one-false.md 测试用例为切入点系统讲解 MD022blanks-around-headings规则的工作原理、include_front_matter参数对 YAML/TOML/JSON front matter 的影响以及!-- markdownlint-configure-file --内联配置的使用方法。读完本文你将能够理解 MD022 的判定逻辑与修复机制掌握lines_above、lines_below和include_front_matter三个参数的精确语义并学会像仓库测试那样用内联配置在单个文档内验证规则行为。一、从一份测试用例说起文档本身即是规则说明书仓库测试目录下有一个看似极简的文档 test/blanks-around-headings-one-false.md全文只有 11 行# Blanks Around Headings One False ## Subheading Text !-- markdownlint-configure-file { blanks-around-headings: { include_front_matter: false } } --它的技术价值远超表面这是一份自带内联配置的测试夹具fixture专门用来验证 MD022 规则在include_front_matter: false默认值下的行为。该文件被 test/markdownlint-test-scenarios.mjs 自动扫描测试框架读取./test目录下所有.md文件逐一对每个文件执行lint()校验{MD022}之类的错误标记并生成快照对应快照文件 test/markdownlint-test-scenarios.mjs.snapshot。在快照中该文件对应的预期结果是errors: []即零违规。换句话说当一个文档没有 front matter时无论include_front_matter配置成false还是true都不会触发额外错误——该参数只有在文档开头存在 front matter 时才产生行为差异。这一点可以从文件的姊妹用例得到交叉印证。二、MD022 规则总览标题必须被空行包围MD022 的规范说明位于 doc/md022.md在 doc/Rules.md 中也有完全一致的收录a namemd022/a锚点之后。规则核心信息如下规则名MD022别名Aliasesblanks-around-headings标签blank_lines、headings可修复Fixable部分违规可由工具自动修复解析器micromark见 lib/md022.mjs 中的parser: micromark2.1 三个配置参数参数类型默认值说明include_front_matterbooleanfalse是否将 front matter 内容计入标题上方的空行检查lines_aboveinteger \| integer[]1标题上方要求的空行数量lines_belowinteger \| integer[]1标题下方要求的空行数量2.2 违规示例与正确写法当标题无论是 ATX 风格#还是 Setext 风格/---前一行或后一行缺少空行时触发该规则# Heading 1 Some text Some more text ## Heading 2修复方式是确保每个标题前后都有空行文档开头或结尾的标题除外# Heading 1 Some text Some more text ## Heading 22.3 设计动机Rationale规则文档给出的理由很实在除了排版美观之外部分 Markdown 解析器例如kramdown不会解析前面没有空行的标题而会把它们当作普通文本处理。因此遵守该规则不仅是风格问题还关系到文档在多种渲染器下的正确性。三、include_front_matter深度解析front matter 是否参与空行判定3.1 默认行为front matter 被忽略默认include_front_matter: false情况下markdownlint 会先通过正则把文档开头的 front matter 区块剥离出来不参与 MD022 的上方空行检查。因此下面的文档不会报告任何违规--- title: Title --- ## Heading注意这里---结束标记与## Heading之间并没有空行但因为 front matter 默认被忽略标题就相当于位于文档开头文档开头不需要空行所以不违规。3.2 开启后的行为front matter 与首个标题之间需要空行若将include_front_matter设为true则要求 front matter 内容与文档第一个标题之间满足配置的空行数量默认 1 行。此时下面的写法会触发 MD022--- title: Title --- ## Heading需要改成--- title: Title --- ## Heading3.3 源码验证getLine与includeFrontMatter的配合在 lib/md022.mjs 中规则读取配置的方式非常直白第 42–45 行const getLinesAbove getLinesFunction(params.config.lines_above); const getLinesBelow getLinesFunction(params.config.lines_below); const includeFrontMatter !!params.config.include_front_matter; const { lines, frontMatterLines } params;params对象由 lint 主流程注入其中lines是正文行数组、frontMatterLines是被剥离的 front matter 行数组见 lib/markdownlint.d.mts 中params的类型定义。关键逻辑在getLine辅助函数第 25–33 行当检查标题上方的行时如果索引超出正文范围即index 0只有includeFrontMatter true且存在 front matter 行时才会从frontMatterLines中取对应行参与空行判定const getLine (lines, index, frontMatterLines, includeFrontMatter) { if ((index 0) (index lines.length)) { return lines[index]; } if (includeFrontMatter (frontMatterLines.length 0) (index 0) (index -frontMatterLines.length)) { return frontMatterLines[frontMatterLines.length index]; } return ; };而检查标题下方空行时第 80 行固定传入false——因为 front matter 只会出现在文档开头标题下方不存在 front matter 参与判定的场景。这就是include_front_matter只影响上方检查的原因。3.4 front matter 从哪来剥离机制的底层实现frontMatterLines的产生来自 lint 主流程中的removeFrontMatterlib/markdownlint.mjs 第 122–141 行它用正则helpers.frontMatterRe定义于 helpers/helpers.cjs 第 22–23 行匹配位于文档最开头的区块支持三种常见格式YAML---开闭TOML开闭或开始、...结束JSON{开闭只有当匹配结果index为 0即真正位于文档开头时才剥离。该正则也可以通过 lint 选项frontMatter自定义lib/markdownlint.mjs 第 808–810 行未显式提供时默认使用helpers.frontMatterRe。由此可以推断include_front_matter的生效前提是文档被识别出 front matter若文档没有 front matter该参数不会改变任何行为——这与本文开头那个测试用例的零违规结果完全一致。四、测试矩阵一行配置差异背后的行为边界把test/目录下与本次主题相关的姊妹用例放在一起对比可以完整还原include_front_matter的行为边界测试文件文档结构内联配置预期结果blanks-around-headings-one-false.md无 front matterinclude_front_matter: false零违规blanks-around-headings-one-true.md无 front matterinclude_front_matter: true零违规blanks-around-headings-one.md无 front matter无内联配置默认配置零违规blanks-around-headings-one-yaml-false.md带 YAML front matterinclude_front_matter: false零违规blanks-around-headings-one-yaml-true.md带 YAML front matterinclude_front_matter: true零违规blanks-around-headings-one-yaml.md带 YAML front matter无内联配置默认配置零违规所有用例的预期错误均为空。其中带 YAML front matter 的用例如 blanks-around-headings-one-yaml-true.md格式如下--- title: Blanks Around Headings One YAML True --- ## Subheading Text !-- markdownlint-configure-file { blanks-around-headings: { include_front_matter: true } } --注意---与## Subheading之间已经有一个空行所以即便include_front_matter: true也满足front matter 与首个标题之间空 1 行的要求从而零违规。你可以把该文件中的空行删掉再运行测试即可观察到 MD022 违规被触发——这正是测试夹具设计的精妙之处用例本身验证的是合规路径而违规路径由{MD022}标记或快照中的错误明细来覆盖例如 blanks-around-headings-1--1.md、blanks-around-headings-arrays.md 等文件就在正文中嵌入了{MD022}期望标记。五、内联配置机制markdownlint-configure-file注释从何而来上述测试用例中反复出现的 HTML 注释并非 markdownlint 的普通注释而是内联配置指令!-- markdownlint-configure-file { blanks-around-headings: { include_front_matter: false } } --lint 主流程在 lib/markdownlint.mjs 的getEnabledRulesPerLineNumber中扫描inlineCommentStartRe定义于 helpers/helpers.cjs解析markdownlint-configure-file指令并以JSON.parse解析注释内嵌的配置对象将其作为该文档的额外配置合并生效。这与内联禁用指令如markdownlint-disable、markdownlint-disable-next-line属于同一套机制可通过noInlineConfig: true选项整体关闭。这意味着任何 markdownlint 用户都可以在单个 Markdown 文件中临时覆写某条规则的参数不必为此新建.markdownlint.json配置文件。这对于验证规则行为、演示文档、以及像仓库测试那样做单文件场景测试都非常实用。5.1 与常规配置文件的关系内联配置优先级高于磁盘上的配置文件如.markdownlint.json、package.json中的markdownlintConfig字段等且只对当前文档生效。在命令行中可用--config指定全局配置再用文件内注释做局部调整在 Node.js API 中则对应lint({ config: ..., files: [...] })的组合。六、lines_above/lines_below精确控制空行数量除了include_front_matterMD022 另外两个参数用于控制标题上下的空行数量语义如下详见 doc/md022.md0允许标题紧贴正文相当于不要求空行1默认要求至少 1 行空行-1任意数量的空行都允许包括 0 行integer[]按标题级别 1–6 依次指定数组长度超过 6 的部分会被忽略不足 6 的部分以默认值 1 补齐数组参数的实现位于 lib/md022.mjs 的getLinesFunction第 12–23 行先以默认值 1 填充长度为 6 的数组再用传入值按索引覆盖最终按getHeadingLevel(heading) - 1取值。测试文件 blanks-around-headings-arrays.md 给出了典型用法blanks-around-headings: { lines_above: [ 1, 2, 3, -1], lines_below: [ -1, 2, 1, 3, -1, 4, 10 ] }即 H1 上方 1 行、H2 上方 2 行、H3 上方 3 行、H4 上方不限H1 下方不限、H2 下方 2 行、H3 下方 1 行……依此类推。该文件在正文中嵌入了大量{MD022}标记来标注预期的违规行是理解按级别差异化配置的最佳参考。6.1 与 MD012 的联动提醒规则文档特别提醒当lines_above或lines_below配置为大于 1 的数值时应同时调整 MD012/no-multiple-blanks——因为 MD012 默认限制连续空行不能超过 1 行两者会互相冲突。测试文件 blanks-around-headings-0-2.md、blanks-around-headings-3-0.md 中都同时关闭了heading-style和no-multiple-blanks正是这个联动约束的实证。6.2 至少 N 行语义与自动修复该规则检查的是至少满足指定数量的空行多余的空行会被忽略文档中明确说明 any extra blank lines are ignored。同时规则声明部分违规可修复在 lib/md022.mjs 中检查不通过时会调用addErrorDetailIf并附带insertText修复信息修复内容为按需插入的空行并且会通过getBlockQuotePrefixText保留引用块blockquote的前缀文本——这意味着引用块内的标题也可以被安全地自动修复。仓库的修复验证流程见 test/markdownlint-test-scenarios.mjslint 之后调用applyFixes生成修复结果并断言修复后不应残留可修复错误。七、本地复现如何在仓库中亲手验证该仓库的测试无需额外安装第三方依赖即可复现依赖均为仓库内置实现。最直接的方式是使用自带的场景测试运行器node --test test/markdownlint-test-scenarios.mjs它将遍历test/下所有.md文件逐个执行 lint、校验{MD022}等期望标记并比对快照输出中可以看到blanks-around-headings-one-false.md、blanks-around-headings-one-yaml-true.md等用例全部通过。若想单独查看某个文件的 lint 结果可以使用调试工具 test/harness.mjsnode test/harness.mjs test/blanks-around-headings-one-false.md它会打印该文件的 micromark token 结构与 lint 结果对象含错误行号、规则名、detail、fixInfo 等字段。你也可以临时修改测试文件的内容例如删除 front matter 与标题之间的空行来观察行为变化但注意仓库为只读镜像如需长期改动请基于自己的副本进行。八、小结参数语义速查场景配置行为文档无 front matter任意include_front_matter参数不生效按普通标题规则检查文档有 front matter且要求 front matter 与首个标题之间留空行include_front_matter: truefront matter 末行计入上方空行检查文档有 front matter但不要求include_front_matter: false默认front matter 被忽略首个标题视作文档开头允许标题紧贴正文lines_above: 0或lines_below: 0对应方向不要求空行空行数量不限lines_above: -1任意数量空行均合规按标题级别差异化lines_above: [1, 2, 3, -1]数组依次对应 H1–H6同时要求多条空行数值 1需同步放宽 MD012否则两者冲突九、延伸阅读MD022 规则完整文档本文章的核心规范来源全部规则速查表含 MD022 及其余 60 条规则的参数与示例MD022 规则实现源码规则测试夹具blanks-around-headings 系列场景测试驱动器与快照front matter 剥离实现removeFrontMatter函数front matter 匹配正则frontMatterRe支持 YAML/TOML/JSON调试工具单文件 lint 输出赞分享开发工具代码质量Lint静态分析【免费下载链接】markdownlintA Node.js style checker and lint tool for Markdown/CommonMark files.项目地址https://gitcode.com/gh_mirrors/ma/markdownlint点击查看免费下载相关推荐markdownlint MD022blanks-around-headings规则详解标题前后空行校验与配置实战markdownlint MD022blanks around headings规则详解标题前后空行校验与配置实战 本文基于 markdownlint 开开发工具代码质量Lint静态分析markdownlint MD022 规则深度解析用 blanks-around-headings 精细控制标题四周的空白行markdownlint MD022 规则深度解析用 blanks around headings 精细控制标题四周的空白行 导读 本文围绕 markdown开发工具代码质量Lint静态分析markdownlint 规则 MD022blanks-around-headings完全指南标题空行环绕检查的原理、配置与修复markdownlint 规则 MD022blanks around headings完全指南标题空行环绕检查的原理、配置与修复 导读 本文基于 mark开发工具代码质量Lint静态分析上一篇Pinpoint集群网络策略可视化Calico Dashboard下一篇离线语音转文字 3 分钟出字幕Buzz 让数据不出本地创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
