
开发工具代码质量Lint静态分析【免费下载链接】markdownlintA Node.js style checker and lint tool for Markdown/CommonMark files.项目地址https://gitcode.com/gh_mirrors/ma/markdownlint点击查看免费下载导读本文以 markdownlint 仓库中的场景测试文件test/lists-with-nesting.md为切入点逐行剖析无序列表与有序列表在嵌套时触发MD032列表周围空行、MD007无序列表缩进、MD004无序列表符号风格、MD029有序列表编号前缀四类规则违例的完整判定过程。读完本文你将掌握 markdownlint 列表嵌套的正确缩进量标准、测试夹具中{MD###}标记的语义与自动断言机制以及如何对照规则源码解释一次 lint 报告中的每一条错误。一、文档定位一个自带答案的列表嵌套测试场景test/lists-with-nesting.md不是普通文档而是一个场景化测试夹具test fixture。它把无序/有序列表的嵌套情况按四组组织Excessive nesting过度缩进Insufficient nesting缩进不足Correct nesting, same type同类型列表的正确嵌套Correct nesting, different types不同类型列表的正确嵌套该文件与test/目录下其他.md文件一样由test/markdownlint-test-scenarios.mjs统一驱动。测试逻辑见 test/markdownlint-test-scenarios.mjs 第 19106 行分为三步用lint({ files: [ file ] })对文件执行完整检查用正则/\{(MD\d)(?::([-]?)(\d))?\}/g解析文件中内联的{MD032}这类标记把它们声明为预期违例可带行号偏移如{MD031:-1}表示上一行触发 MD031断言实际 lint 结果与标记完全一致多一条、少一条都算失败并比对修复后的快照test/markdownlint-test-scenarios.mjs.snapshot。因此文档中每一处{MD032}、{MD007}等标记都是经过完整 lint 验证的官方预期结论直接可作为学习列表嵌套规则的权威答案。二、过度缩进Excessive nestingMarkdown 语法合法 ≠ lint 通过- one 1. two 1. three - four 1. one - two - three 1. four第一组中无序列表项- one下挂了缩进 3 个空格的1. two、1. three第二组中有序列表项1. one下挂了缩进 4 个空格的- two、- three。这一组完全没有{MD###}标记含义是这些写法虽然缩进量偏大常见规范要求 2 空格但MD007默认只要求子列表缩进为配置值默认 2 空格的整数倍。结合 lib/md007.mjs 第 2123 行与第 5758 行可以看到核心计算const indent Number(params.config.indent || 2); const expectedIndent baseIndent (startIndented ? startIndent : 0) (nesting * indent);expectedIndent等于「嵌套层级 × 配置缩进」MD007只对每个无序列表项前缀的实际列位置与期望位置的差值报错并不校验是否恰好等于最小值。所以- one下缩进 3 空格、1. one下缩进 4 空格都属于合法但偏多的嵌套测试断言为 0 违例。提示若想让这种写法也被报出需配置MD007: { indent: 4 }配合每级必须恰好 4 空格的编辑规范从源码看规则只比较实际缩进与期望缩进是否相等配置为 4 时 3 空格子项即会被报为Expected: 4; Actual: 3。三、缩进不足Insufficient nesting同一行可能同时违反多条规则- one {MD032} 1. two {MD032} - three {MD032} 1. one {MD032} - two {MD007} {MD032} 1. three {MD032}这是全文违例密度最高的一段需要逐行拆解{MD032}× 6MD032blanks-around-lists要求每个顶层列表前后都必须有空行文档首尾除外。这里段落之间只有 1 个空行分隔列表第 17 行- one与第 18 行1. two、第 22 行- two等行彼此直接相邻被判定为列表间缺少空行。查看 lib/md032.mjs 第 2447 行规则只遍历顶层列表filterByPredicate找listOrdered/listUnordered检查其startLine的上一行与视觉末尾的下一行是否为空白行每个缺失处生成一条addErrorContext。{MD007}× 1第 22 行- two仅缩进 1 空格低于默认 2 空格MD007报Expected: 2; Actual: 1。注意它与{MD032}同时出现——markdownlint 各规则彼此独立同一行可携带多条违例快照中第 22 行因此有 4 条 error2 条 MD032 1 条 MD007且另有上下文重复计次。第 18 行1. two未标{MD007}因为它是有序列表项而MD007只针对无序列表源码第 89 行的unorderedListTypes仅含blockQuotePrefix、listItemPrefix、listUnordered且嵌套计算遇到listOrdered祖先会置为-1跳过见 lib/md007.mjs 第 4047 行。对照快照test/markdownlint-test-scenarios.mjs.snapshot 第 3203032160 行本段共产生 11 条 error全部对应上述标记验证了一处文本、多条规则并发判定的行为。四、同类型列表的正确嵌套层级递进且对齐- one - two - three - four - five - six - seven 1. one 1. two 1. three 1. four 1. five 1. six 1. seven本组展示了零违例的两类写法无序列表每层缩进恰好 2 空格- two在 2 列、- six在 6 列、- seven在 8 列且全程统一使用-符号同时满足MD007缩进2×层级与MD004风格一致有序列表1. one→ 缩进 3 空格1. two4 列→ 缩进 6 空格1. five7 列→ 缩进 9 空格1. seven10 列。每级恰好列表标记位数2 列 1 空格 层级且编号全部从1重新开始符合MD029默认one_or_ordered风格中子列表可重置为 1的规则。为什么有序子列表缩进 3 空格不算 MD007 违例关键在 lib/md007.mjs 第 89 行MD007的 token 集合只包含listUnordered类型第 4345 行更明确——当向上查找父级时若遇到listOrderednesting被置为-1即该子列表的缩进完全不参与 MD007 判定有序列表参与的是MD030的标记后空格规则。文档注释也直接写明本规则仅在父列表全部为无序列表时才作用于子列表否则有序列表的额外缩进会干扰规则判断见 doc/md007.md。五、不同类型列表的正确嵌套类型切换的缩进规律- one 1. two 1. three - four 1. one - two - three 1. four无序列表项内嵌有序列表缩进 2 空格、子项在 3 列或有序列表项内嵌无序列表缩进 2 空格、子项在 3 列均无标记。这说明 markdownlint 对类型不同的父子列表不要求 4 空格对齐2 空格即可成立——与 CommonMark 的列表项内容从标记后 1 空格处开始规则一致。此处1.后接- two缩进 2 空格3 列正好让子列表内容起点与父项文本two的起点第 3 列对齐。六、深层混合嵌套交替类型直至 8 层- one 1. two - three 1. four - five 1. six - seven 1. eight 1. one - two 1. three - four 1. five - six 1. seven - eight两组分别以-与1.开头交替嵌套 8 层全程零违例。规律是当嵌套类型切换时子项从父项标记后 1 空格处开始缩进即1.子项缩进 2 空格、-子项在交替后同样按 2 空格递进而MD007只对纯无序链生效类型一旦掺入有序列表即跳过因此这种紧凑的混合缩进完全合法。七、同层内的标记堆叠* 1. Item组合陷阱* 1. Item {MD004} {MD007} * 2. Item {MD004} {MD007} {MD029} * 3. Item {MD004} {MD007} {MD029}最后三行是全文最隐蔽的用例* 1. Item中*与1.之间用空格分隔会被 CommonMark 解析为无序列表项内嵌有序列表而非无序列表 文本。由此同时触发MD004Expected: dash; Actual: asterisk全文其余无序列表使用-按照consistent默认风格*与-不一致。源码见 lib/md004.mjs 第 5052 行——consistent风格以第一个遇到的无序列表符号为准。修复建议是将其替换为-快照中fixInfo.insertText即为-。MD007Expected: 0; Actual: 1第 97 行*前有 1 个空格缩进作为顶层无序列表项其期望缩进为 0。MD029仅第 98、99 行* 2. Item与* 3. Item的子有序列表编号递增但未从 1 开始。结合 lib/md029.mjs 第 4050 行规则取每个listOrdered的前两个前缀值判断是否递增模式——2、3不满足第二个等于 1 且第一个为 0于是按ordered风格要求从1/2/3开始第 98 行报Expected: 1; Actual: 2第 99 行报Expected: 1; Actual: 3。而第 97 行的子列表只有一个1.长度不足 2 不会触发递增判断故无 MD029。该段 9 行内堆叠 8 条 error快照第 3183732027 行逐条可查是所有列表相关规则在符号 缩进 编号 空行四维度同时作用的最佳演示。八、把标记解读为诊断说明书四个规则的行为边界综合整个文件可提炼出四规则的判定边界均以默认配置为准规则参数见 doc/md004.md、doc/md007.md、doc/md029.md、[doc/md032.md)规则别名检查对象默认参数核心判定MD004ul-style无序列表符号style: consistent可选asterisk/dash/plus/sublist全文符号风格一致MD007ul-indent无序列表缩进indent: 2、start_indent: 2、start_indented: false每层缩进 层级 × indent仅作用于父级全为无序的链MD029ol-prefix有序列表编号style: one_or_ordered可选one/ordered/zero前缀从 1 或 0 开始或按 1/2/3 递增MD032blanks-around-lists所有顶层列表无参数列表前后必须有空行文档首尾除外值得注意的边界细节MD007 不检查缩进过多只要实际缩进等于nesting × indent即通过4 空格/6 空格嵌套不报错Excessive nesting组验证MD007 忽略含有序父级的链混合类型嵌套完全交给缩进对齐直觉规则主动让路Correct nesting, different types组验证MD032 只盯顶层列表子列表间的空行不归它管由MD031围栏代码块、MD028引用块空行等规则各司其职MD029 的递增判断基于每张有序列表子列表编号重置为 1 不违规但2/3/4这类中间断档会被要求改回1* 2. Item组验证。九、如何复现与扩展运行测试与编写自己的场景复现本文全部结论在仓库根目录执行node --test test/markdownlint-test-scenarios.mjs该命令会对test/*.md全部场景执行断言lists-with-nesting.md正是其中之一如需单独查看原始 lint 输出含fixInfo修复建议可参照 test/harness.mjs 的用法node test/harness.mjs test/lists-with-nesting.md编写自己的列表场景时遵循三步在test/下新建.md文件正文直接使用实际 Markdown 内容在预期违例行的行内追加{MD###}标记需要声明上一行/下一行时使用{MD###:-1}/{MD###:1}需要精确指定行号时使用{MD###:行号}语法定义见 test/markdownlint-test-scenarios.mjs 第 4063 行运行上述测试命令测试框架会自动比对实际结果并生成/校验快照。若以编程方式直接调用可参考 README.md 的Usage一节使用 Promise 风格一次性检查多个文件import { lint as lintPromise } from markdownlint/promise; const results await lintPromise({ files: [ test/lists-with-nesting.md ] }); console.dir(results, { colors: true, depth: null });返回对象按文件名分组每条 error 包含lineNumber、ruleNames如[ MD007, ul-indent ]、errorDetail如Expected: 0; Actual: 1与fixInfo可自动修复的编辑指令格式详见 README.md 第 9661003 行的示例。十、总结test/lists-with-nesting.md用 99 行文本完整覆盖了 markdownlint 对列表嵌套的四类核心判定缩进量级MD007默认每层 2 空格、符号风格MD004默认全文一致、编号规则MD029默认 1/1/1 或 1/2/3、空行隔离MD032顶层列表前后留白。更重要的是它以{MD###}标记形式把正确答案直接嵌入文档配合 test/markdownlint-test-scenarios.mjs 的自动断言机制形成了一份可运行、可回归的规则行为说明书——无论是排查自己文档中的列表报错还是理解各规则在类型混合、层级深嵌套下的边界这份场景文件都是最直观的参考起点。赞分享开发工具代码质量Lint静态分析【免费下载链接】markdownlintA Node.js style checker and lint tool for Markdown/CommonMark files.项目地址https://gitcode.com/gh_mirrors/ma/markdownlint点击查看免费下载相关推荐markdownlint 列表解析边界场景详解段落中的数字为何触发 MD029/MD030/MD032/MD004markdownlint 列表解析边界场景详解段落中的数字为何触发 MD029/MD030/MD032/MD004 markdownlint 是 Node.j开发工具代码质量Lint静态分析Wand-Enhancer 本地补丁实操WeMod 客户端离线增强怎么跑起来Wand Enhancer 本地补丁实操WeMod 客户端离线增强怎么跑起来 Wand Enhancer 是一个开源工具在本地改写 WeModWand客开发工具代码质量Lint静态分析markdownlint MD032/blanks-around-lists 规则详解列表前后必须留空行markdownlint MD032/blanks around lists 规则详解列表前后必须留空行 导读 本文深入解析 markdownlint 的 M开发工具代码质量Lint静态分析上一篇Logto 云片Yunpian短信连接器接入实战从 API Key 申请到验证码登录全流程下一篇douyin-downloader 抖音批量下载指南3 步搭好无水印增量下载创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考