Assignment【免费下载链接】curriculumThe open curriculum for learning web development项目地址: https://gitcode.com/GitHub_Trending/cu/curriculumValid div due to each tag being surrounded by blank lines.这里的div与/div各自前后均为空行完全满足规则要求因此不会触发任何 TOP005 错误。这也是课程正文中最常见的提示框/面板写法——lesson-content__panel配合markdown1让markdown-it在 div 内部继续解析 Markdown 内容。豁免场景二单行 HTML 标签非多行天然合法规则只针对单独占据一行、且仅包含一个开/闭标签的多行 HTML 标签。如果标签是单行内联形式则不在检查范围内divValid single-line div/div更复杂一点的行内混排同样合法divValid single-line div/divMight even have other spanparagraph/span content with it.原因在于规则判定依赖的正则^(?!!)\/?[^]*$见 规则源码要求整行 trim 后恰好是一个完整的标签以开头、结尾、中间不含、且非!--注释开头。上述两行的 trim 结果都不满足整行只有标签的条件因此被跳过。豁免场景三markdown 代码块内的 HTML——唯一的内容例外ignored_tags.md揭示了一个重要细节代码块分隔符本身就是合法的包围物。规则源码中用于校验前后行的正则blankCodeBlockRegex /^$|^{3,4}.$/表明一行只要为空行^$或以 34 个反引号开头^{3,4}.$即视为合法包围。正因如此markdown围栏代码块内的多行 HTML 标签也被放行——此时这些标签是被讲解的示例而非真实页面标记markdown div The only exception to blank lines is a code block delimiter. /div 注意这里的措辞The only exception to blank lines is a code block delimiter——即空行的唯一替代品就是代码块分隔符。也就是说对于markdown代码块虽然内部的div并不满足两侧都是空行但只要两侧是空行或代码块围栏行就仍然合法。这正是 TOP005.md 文档 中示例所表达的行为第二个开标签被围栏分隔符和空行包围两者均为合法。豁免场景四html / jsx / erb / ejs / ruby / javascript 围栏代码块这是ignored_tags.md中占比最大的豁免类型当多行 HTML 标签出现在特定语言围栏中时规则整体跳过不再要求空行。测试夹具逐一展示了六种语言html div p Does not flag when used in an HTML example /p /div jsx p Also does not flag when used in JSX code blocks /p erb % if language.isErb? % pAlso does not flag when used in erb code blocks/p % end % ejs % if (isEjs) { % pAlso does not flag when used in ejs code blocks/p % } % ruby if ruby? html_fragment ~HTML pDoes not flag when used in ruby code blocks/p HTML end javascript const htmlString pDoes not flag when used in JavaScript code blocks, e.g. template literals./p ; 这一行为直接映射到 规则源码 中的豁免清单const IGNORED_FENCE_TYPES [html, jsx, erb, ejs, ruby, javascript];源码注释也解释了意图HTML code in HTML/JSX code blocks should not be flagged. We only want to flag HTML tags we use for actual markup, or md code block examples of such.——即规则只针对真实页面标记以及markdown代码块中作为示例的此类标记而对html/jsx等代码块中的 HTML 一概放行。ruby、javascript、erb、ejs被纳入清单是因为这些语言的字符串、模板、Heredoc 中经常会内嵌 HTML 片段误报会造成严重噪音。实现细节行区间过滤豁免并非逐行判断而是按行区间整体排除。规则通过markdown-it的 token 流过滤出围栏 token 及其map起始行、结束行区间再判断目标行是否落入任一被忽略的围栏区间内const ignoredFencesLineRanges params.parsers.markdownit.tokens .filter((token) { return token.type fence IGNORED_FENCE_TYPES.includes(token.info); }) .map((token) token.map); const isWithinIgnoredFence (lineNumber) { return ignoredFencesLineRanges.some( (range) range[0] lineNumber lineNumber range[1] ); };在遍历到每个孤立 HTML 标签行时若isWithinIgnoredFence(lineNumber)为真则直接return跳过。这意味着只要标签行位于上述六类围栏的内部不含围栏分隔行本身无论其前后是否为空行都不会报错。豁免场景五markdownlint 行级忽略指令ignored_tags.md还展示了另一层硬豁免机制——markdownlint 自带的忽略指令!-- markdownlint-disable-next-line -- ### Will not flag ignore comments which require being directly followed by the line to ignoremarkdownlint-disable-next-line是 markdownlint 官方提供的行级开关紧跟其后的那一行即使违反规则也不会被报告。测试夹具用它来说明即便标题行包含代码在正常规则下可能触发其他 lint 规则如标题内禁代码只要前置了该注释就会被静默忽略。这属于规则系统层面的豁免与 TOP005 的判定逻辑正交但同样在零报错夹具中扮演了关键角色。正反对照flagged_tags.md中的命中场景理解豁免之后再看反例 flagged_tags.md 能帮你建立完整的判定边界。该夹具刻意构造了若干必报错场景例如开标签后紧跟非空行无空行也无围栏行连续两个 HTML 块之间没有空行chained HTML blocksmarkdown代码块内闭标签上方既非空行也非围栏分隔行即使标签带有缩进如p也照报不误——规则基于trim()后判定缩进不影响命中。而对应的修复结果 fixed_flagged_tags.md 展示了自动修复的全部形态在缺失处补上空行使每个孤立标签两侧都满足空行或代码块分隔符。底层原理为什么强制空行如此重要规则如此苛刻根源在于markdown-it对 HTML 块的解析方式。TOP005 的 Rationale见 markdownlint/docs/TOP005.md明确指出在遇到空行之前HTML 开标签之后的所有内容会被合并进同一个html_blocktoken其中的文本不会被拆分为独立的 Markdown 元素 token因此无法触发任何基于 token 的 lint 规则。这意味着下面这段 Markdown 即使满是错误也不会被任何规则捕获div classlesson-note markdown1 #### This title should trigger the blanks around headings rule 1. [this should trigger the descriptive links rule](#rationale) 2. this should trigger the lazy list numbering rule /div标题规则、描述性链接规则、惰性列表编号规则全部失效。而一旦强制 HTML 标签被空行或代码块分隔符包围html_block就被切碎成独立 token内部内容得以被逐条规则正常解析与报错。因此 TOP005 的定位并非排版洁癖而是守护整个 lint 体系正确性的地基——它保证维护者在课程正文的 HTML 面板中不会漏掉任何真正的格式错误。自动化验证测试如何证明零报错ignored_tags.md的零报错身份由 TOP005.test.js 中的用例固化it(Does not flag when no rule violations, async () { const filePath ./ignored_tags.md; const lintErrors await getLintErrors(filePath); assert.deepEqual(lintErrors, []); });该用例通过 test_utils/lint.js 提供的getLintErrors执行npm run lint -- 文件路径断言返回的错误数组为空。与此同时flagged_tags.md用例则断言了 13 条精确的错误输出每条都含文件行号、规则名、描述与具体上下文例如...tests/flagged_tags.md:19 error TOP005/blanks-around-multiline-html-tags Multiline HTML tags should be surrounded by blank lines or code block delimiters [Expected a blank line or a code block delimiter () after the tag] [Context: div classlesson-content__panel markdown1]修复方向则由Fix分组验证fixLintErrors(./flagged_tags.md)的输出必须与 fixed_flagged_tags.md 逐字节一致见 test_utils/fix.js 的实现它通过npm run lint -- --format输出修复后内容并去除 CLI 噪音。整套测试基于 Node 内置测试运行器node --test在仓库根目录执行npm run test即可运行见 package.json 中的scripts.test。判定边界速查表场景是否触发 TOP005依据多行 HTML 标签两侧均有空行否ignored_tags.md单行内联标签div.../div或混排文本否行级正则^(?!!)\/?[^]*$不命中markdown围栏内标签两侧为空行或围栏行否blankCodeBlockRegex /^$|^{3,4}.*$/markdown围栏内标签一侧既非空行也非围栏行是flagged_tags.mdhtml/jsx/erb/ejs/ruby/javascript围栏内的标签否IGNORED_FENCE_TYPES行区间豁免连续 HTML 块之间无空行是前后行校验失败含下一行仍是 HTML 标签的相邻特判带缩进的多行标签是判定基于trim()后内容缩进不影响markdownlint-disable-next-line后的行否markdownlint 行级忽略指令在仓库中亲手验证仓库是只读的你可以通过以下方式在本机复现验证需先按 package.json 安装依赖项目使用markdownlint-cli2# 安装依赖 npm install # 运行全部测试含 TOP005 的零报错与修复断言 npm run test # 单独对零报错夹具做 lint预期无任何输出 npm run lint -- markdownlint/TOP005_blanksAroundMultilineHtmlTags/tests/ignored_tags.md # 对反例夹具做 lint预期输出 13 条 TOP005 错误 npm run lint -- markdownlint/TOP005_blanksAroundMultilineHtmlTags/tests/flagged_tags.md【免费下载链接】curriculumThe open curriculum for learning web development项目地址: https://gitcode.com/GitHub_Trending/cu/curriculum创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Assignment
Assignment【免费下载链接】curriculumThe open curriculum for learning web development项目地址: https://gitcode.com/GitHub_Trending/cu/curriculumValid div due to each tag being surrounded by blank lines.这里的div与/div各自前后均为空行完全满足规则要求因此不会触发任何 TOP005 错误。这也是课程正文中最常见的提示框/面板写法——lesson-content__panel配合markdown1让markdown-it在 div 内部继续解析 Markdown 内容。豁免场景二单行 HTML 标签非多行天然合法规则只针对单独占据一行、且仅包含一个开/闭标签的多行 HTML 标签。如果标签是单行内联形式则不在检查范围内divValid single-line div/div更复杂一点的行内混排同样合法divValid single-line div/divMight even have other spanparagraph/span content with it.原因在于规则判定依赖的正则^(?!!)\/?[^]*$见 规则源码要求整行 trim 后恰好是一个完整的标签以开头、结尾、中间不含、且非!--注释开头。上述两行的 trim 结果都不满足整行只有标签的条件因此被跳过。豁免场景三markdown 代码块内的 HTML——唯一的内容例外ignored_tags.md揭示了一个重要细节代码块分隔符本身就是合法的包围物。规则源码中用于校验前后行的正则blankCodeBlockRegex /^$|^{3,4}.$/表明一行只要为空行^$或以 34 个反引号开头^{3,4}.$即视为合法包围。正因如此markdown围栏代码块内的多行 HTML 标签也被放行——此时这些标签是被讲解的示例而非真实页面标记markdown div The only exception to blank lines is a code block delimiter. /div 注意这里的措辞The only exception to blank lines is a code block delimiter——即空行的唯一替代品就是代码块分隔符。也就是说对于markdown代码块虽然内部的div并不满足两侧都是空行但只要两侧是空行或代码块围栏行就仍然合法。这正是 TOP005.md 文档 中示例所表达的行为第二个开标签被围栏分隔符和空行包围两者均为合法。豁免场景四html / jsx / erb / ejs / ruby / javascript 围栏代码块这是ignored_tags.md中占比最大的豁免类型当多行 HTML 标签出现在特定语言围栏中时规则整体跳过不再要求空行。测试夹具逐一展示了六种语言html div p Does not flag when used in an HTML example /p /div jsx p Also does not flag when used in JSX code blocks /p erb % if language.isErb? % pAlso does not flag when used in erb code blocks/p % end % ejs % if (isEjs) { % pAlso does not flag when used in ejs code blocks/p % } % ruby if ruby? html_fragment ~HTML pDoes not flag when used in ruby code blocks/p HTML end javascript const htmlString pDoes not flag when used in JavaScript code blocks, e.g. template literals./p ; 这一行为直接映射到 规则源码 中的豁免清单const IGNORED_FENCE_TYPES [html, jsx, erb, ejs, ruby, javascript];源码注释也解释了意图HTML code in HTML/JSX code blocks should not be flagged. We only want to flag HTML tags we use for actual markup, or md code block examples of such.——即规则只针对真实页面标记以及markdown代码块中作为示例的此类标记而对html/jsx等代码块中的 HTML 一概放行。ruby、javascript、erb、ejs被纳入清单是因为这些语言的字符串、模板、Heredoc 中经常会内嵌 HTML 片段误报会造成严重噪音。实现细节行区间过滤豁免并非逐行判断而是按行区间整体排除。规则通过markdown-it的 token 流过滤出围栏 token 及其map起始行、结束行区间再判断目标行是否落入任一被忽略的围栏区间内const ignoredFencesLineRanges params.parsers.markdownit.tokens .filter((token) { return token.type fence IGNORED_FENCE_TYPES.includes(token.info); }) .map((token) token.map); const isWithinIgnoredFence (lineNumber) { return ignoredFencesLineRanges.some( (range) range[0] lineNumber lineNumber range[1] ); };在遍历到每个孤立 HTML 标签行时若isWithinIgnoredFence(lineNumber)为真则直接return跳过。这意味着只要标签行位于上述六类围栏的内部不含围栏分隔行本身无论其前后是否为空行都不会报错。豁免场景五markdownlint 行级忽略指令ignored_tags.md还展示了另一层硬豁免机制——markdownlint 自带的忽略指令!-- markdownlint-disable-next-line -- ### Will not flag ignore comments which require being directly followed by the line to ignoremarkdownlint-disable-next-line是 markdownlint 官方提供的行级开关紧跟其后的那一行即使违反规则也不会被报告。测试夹具用它来说明即便标题行包含代码在正常规则下可能触发其他 lint 规则如标题内禁代码只要前置了该注释就会被静默忽略。这属于规则系统层面的豁免与 TOP005 的判定逻辑正交但同样在零报错夹具中扮演了关键角色。正反对照flagged_tags.md中的命中场景理解豁免之后再看反例 flagged_tags.md 能帮你建立完整的判定边界。该夹具刻意构造了若干必报错场景例如开标签后紧跟非空行无空行也无围栏行连续两个 HTML 块之间没有空行chained HTML blocksmarkdown代码块内闭标签上方既非空行也非围栏分隔行即使标签带有缩进如p也照报不误——规则基于trim()后判定缩进不影响命中。而对应的修复结果 fixed_flagged_tags.md 展示了自动修复的全部形态在缺失处补上空行使每个孤立标签两侧都满足空行或代码块分隔符。底层原理为什么强制空行如此重要规则如此苛刻根源在于markdown-it对 HTML 块的解析方式。TOP005 的 Rationale见 markdownlint/docs/TOP005.md明确指出在遇到空行之前HTML 开标签之后的所有内容会被合并进同一个html_blocktoken其中的文本不会被拆分为独立的 Markdown 元素 token因此无法触发任何基于 token 的 lint 规则。这意味着下面这段 Markdown 即使满是错误也不会被任何规则捕获div classlesson-note markdown1 #### This title should trigger the blanks around headings rule 1. [this should trigger the descriptive links rule](#rationale) 2. this should trigger the lazy list numbering rule /div标题规则、描述性链接规则、惰性列表编号规则全部失效。而一旦强制 HTML 标签被空行或代码块分隔符包围html_block就被切碎成独立 token内部内容得以被逐条规则正常解析与报错。因此 TOP005 的定位并非排版洁癖而是守护整个 lint 体系正确性的地基——它保证维护者在课程正文的 HTML 面板中不会漏掉任何真正的格式错误。自动化验证测试如何证明零报错ignored_tags.md的零报错身份由 TOP005.test.js 中的用例固化it(Does not flag when no rule violations, async () { const filePath ./ignored_tags.md; const lintErrors await getLintErrors(filePath); assert.deepEqual(lintErrors, []); });该用例通过 test_utils/lint.js 提供的getLintErrors执行npm run lint -- 文件路径断言返回的错误数组为空。与此同时flagged_tags.md用例则断言了 13 条精确的错误输出每条都含文件行号、规则名、描述与具体上下文例如...tests/flagged_tags.md:19 error TOP005/blanks-around-multiline-html-tags Multiline HTML tags should be surrounded by blank lines or code block delimiters [Expected a blank line or a code block delimiter () after the tag] [Context: div classlesson-content__panel markdown1]修复方向则由Fix分组验证fixLintErrors(./flagged_tags.md)的输出必须与 fixed_flagged_tags.md 逐字节一致见 test_utils/fix.js 的实现它通过npm run lint -- --format输出修复后内容并去除 CLI 噪音。整套测试基于 Node 内置测试运行器node --test在仓库根目录执行npm run test即可运行见 package.json 中的scripts.test。判定边界速查表场景是否触发 TOP005依据多行 HTML 标签两侧均有空行否ignored_tags.md单行内联标签div.../div或混排文本否行级正则^(?!!)\/?[^]*$不命中markdown围栏内标签两侧为空行或围栏行否blankCodeBlockRegex /^$|^{3,4}.*$/markdown围栏内标签一侧既非空行也非围栏行是flagged_tags.mdhtml/jsx/erb/ejs/ruby/javascript围栏内的标签否IGNORED_FENCE_TYPES行区间豁免连续 HTML 块之间无空行是前后行校验失败含下一行仍是 HTML 标签的相邻特判带缩进的多行标签是判定基于trim()后内容缩进不影响markdownlint-disable-next-line后的行否markdownlint 行级忽略指令在仓库中亲手验证仓库是只读的你可以通过以下方式在本机复现验证需先按 package.json 安装依赖项目使用markdownlint-cli2# 安装依赖 npm install # 运行全部测试含 TOP005 的零报错与修复断言 npm run test # 单独对零报错夹具做 lint预期无任何输出 npm run lint -- markdownlint/TOP005_blanksAroundMultilineHtmlTags/tests/ignored_tags.md # 对反例夹具做 lint预期输出 13 条 TOP005 错误 npm run lint -- markdownlint/TOP005_blanksAroundMultilineHtmlTags/tests/flagged_tags.md【免费下载链接】curriculumThe open curriculum for learning web development项目地址: https://gitcode.com/GitHub_Trending/cu/curriculum创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考