尧图网页设计 
curriculum 仓库 Markdown 链接规范实战TOP001 描述性链接文本检测规则解析【免费下载链接】curriculumThe open curriculum for learning web development项目地址: https://gitcode.com/GitHub_Trending/cu/curriculum本指南围绕开源课程仓库 cu/curriculum 中自研的 Markdown 静态检查规则TOP001descriptive-link-text-labels展开重点以测试用例 this_or_here.md 与 blacklisted_label_text.md 为切入点讲清楚该规则“什么会被标记、什么不会被标记、为什么”并结合 规则源码 与 单元测试 还原其检测原理。读完你将掌握描述性链接文本的编写标准、该规则的判定边界与误报场景以及如何在本地运行 lint 与测试验证。规则背景为什么链接文本必须“可描述”TOP001 规则的完整定义与设计动机记录在 规则文档 中其标签为accessibility与links别名descriptive-link-text-labels。它服务的核心场景是当文档中的链接文本本身无法让读者尤其是使用屏幕阅读器等辅助技术的用户理解链接指向的内容时该规则将触发告警。这背后的可访问性原理是辅助技术用户经常通过“跳转链接列表”来浏览页面此时链接文本被脱离上下文单独朗读。像here或click this这样的文本在脱离上下文后完全没有信息量而像video、docs这类文本虽然包含一个名词但同样无法让用户预判目标内容。因此课程仓库要求链接文本“本身就足够描述性”这正是 TOP001 要强制落实的规范。规则触发条件两种被标记的链接文本依据 TOP001 规则文档 与 规则源码链接满足以下任一条件即触发错误链接文本中包含单词 “this” 或 “here”不区分大小写且要求是独立单词详见下文“词边界”小节链接文本整体精确命中黑名单词条——即文本内容不包含 this/here但本身过于笼统例如 “video”“article”“docs”“documentation”“homepage” 等。两条规则分别对应两种不同的错误详情提示命中 this/here 时提示Expected text to not include the words this or here. Use a more descriptive label that clearly conveys the purpose or content of the link.命中黑名单时提示文本 is not sufficiently descriptive by itself. Use a more descriptive label that clearly conveys the purpose or content of the link.测试用例之一this_or_here.md 的判定边界this_or_here.md 是一份“只包含该规则违规、不包含其他规则违规”的专用测试夹具测试文件规范见 docs/README.md。它将链接分为两组直观展示了规则的判定边界。不应被标记的链接合法正例Some descriptive link text He replied With is Where Heresy Some text with the word video Some text with the words documentation, an article, docs, the docs, page, a video, articles, resource, their docs这些链接之所以合法原因有三He replied中的 “replied” 只是含 “here” 的字母串并非单词 “here”Where、Heresy同理仅包含 “here” 子串Some text with the word video这类文本中虽然出现了黑名单词 “video”“docs”“page” 等但黑名单要求整个链接文本精确匹配长文本不构成命中。应被标记的链接违规反例this This video here Click here This other thing This blog post about flex-grow will be flagged as a false positive, but could still be updated This will get caught and so will this as separate matches这些链接全部因为包含独立单词 “this” 或 “here” 而被标记。注意两个细节This video开头的大写 “This” 同样会被捕获正则开启了i忽略大小写标志[This blog post about flex-grow will be flagged as a false positive...]是规则的有意误报false positive即使文本主体相当描述性只要出现了 “this” 一词规则依然会标记因为辅助技术用户跳读链接时 “This...” 的指代性依然不明确。测试用例之二blacklisted_label_text.md 的精确匹配blacklisted_label_text.md 展示的是黑名单机制链接文本整体命中黑名单词条时被标记例如video videos a video docs the documentation their documentation page their homepage playlist a playlist注意匹配方式源码中调用的是BLACKLISTED_LINK_TEXT.includes(linkContentString.toLowerCase())即把链接文本转小写后做数组精确查找而不是子串匹配。因此a video命中词条a video而Some text with the word video不命中。完整黑名单清单以下 22 个词条定义在 规则源码 的BLACKLISTED_LINK_TEXT数组中video, videos, a video, playlist, a playlist, article, articles, an article, doc, docs, the docs, their docs, documentation, the documentation, their documentation, resource, library, page, homepage, the homepage, their homepage,这些词条的共同特征是它们是“媒体/内容类型名词”或“泛指代词”单独作为链接文本无法传达目标内容。源码实现从 Token 流到正则判定TOP001 是一个基于markdownit解析器的自定义规则项目要求所有自定义规则的parser字段必须为markdownit见 docs/README.md。核心实现位于 TOP001_descriptiveLinkTextLabels.js处理流程如下筛选含链接的 Token从params.parsers.markdownit.tokens中过滤出子节点里存在link_open的 token定位链接文本区间对每个link_opentoken在其后续子节点中查找link_close的位置中间夹着的就是链接文本的 token 序列还原链接文本字符串遍历文本 token 并拼接其中code_inline类型会加上反引号包裹\${token.content}使行内代码的语义被保留双重判定用正则/.*?(?!(\w|))(this|here)(?!(\w|)).*?/i检测是否包含独立单词 this/here将拼接出的文本toLowerCase()后与黑名单数组做includes精确匹配上报错误命中任一条件即调用onError输出行号、详情与文本形式的上下文。词边界正则的细节判定 this/here 的正则/.*?(?!(\w|))(this|here)(?!(\w|)).*?/i使用了负向零宽断言来实现“独立单词”匹配(?!(\w|)) 保证 this/here 之前不是字母、数字、下划线或反引号(?!(\w|)) 保证之后也不是字母、数字、下划线或反引号结尾的i标志使其大小写不敏感。这正是He replied、Where、Heresy不会被误报的原因——replied/Where/Heresy中的here子串前后都紧邻字母不符合词边界要求。源码注释还提供了 regexr.com/7sdtj 作为在线验证工具。测试如何验证断言驱动的回归保障规则的所有行为都由 Node 内置测试运行器node --test驱动验证见 TOP001.test.js。该测试文件通过getLintErrors工具对两份测试夹具执行真实的 lint 命令并逐一断言错误输出对./this_or_here.md断言产生8 条错误依次对应第 23、24、25、26、27、28 行以及第 29 行同一行内的两条独立链接[This will get caught]与[this as separate matches]每条错误都包含规则名、描述与Context: [this]形式的上下文对./blacklisted_label_text.md断言产生10 条错误覆盖第 2332 行的全部黑名单链接另外测试还验证规则对象的information字段正确指向规则文档。其中getLintErrors的实现位于 test_utils/lint.js它对目标文件执行npm run lint -- 文件路径若命令以非零码退出则把stderr按行拆分后作为错误数组返回若退出码为 0无违规则返回空数组。这种“以真实 CLI 输出作为断言依据”的方式保证了测试与生产 lint 行为完全一致。如何修复把 this/here 和笼统名词改写成具体内容规则文档 TOP001.md 给出了修复原则删除 “here”“this”改用能清楚传达链接目的或内容的文本必要时同步改写周围句子。例如# 违规 You can read more about variables in JavaScript [here](https://example.com). [This article](https://example.com) provides more information about closures. # 修复 You can read more about [variables in JavaScript](https://example.com). [An in-depth article about closures in JavaScript](https://example.com) provides more information.即使文本本身已有一定描述性只要包含 this/here 仍会被标记因此也要改写# 违规仍会命中 this [Here is a comprehensive guide to understanding closures](https://example.com). # 修复 [Comprehensive guide to understanding closures](https://example.com)对于黑名单命中的笼统名词修复思路是在链接文本中补充具体主题关键词# 违规 For more information, watch this [video](https://example.com) about the CSS box model. You can read more about it in the [documentation](https://example.com). # 修复 For more information, watch this [video about the CSS box model](https://example.com). You can read more about it in the [Proc class documentation](https://example.com).本地运行与验证本仓库通过 package.json 暴露三条命令依赖markdownlint-cli2npm run lint执行markdownlint-cli2对仓库 Markdown 文件做静态检查TOP001 属于其中一条自定义规则npm run fix执行markdownlint-cli2 --fix自动修复可修复项TOP001 因依赖上下文语义文档明确标注不可自动修复即Fixable via script: Not fixable due to being context-basednpm run test执行node --test运行全部自定义规则测试其中就包含 TOP001.test.js 对两份测试夹具的断言。若只想单独观察 TOP001 的报错效果可以对测试夹具直接跑 lint例如对this_or_here.md执行检查会得到包含行号、规则名、错误详情与链接上下文的多行错误输出。需要注意的是本仓库为只读资源上述命令仅用于本地查看与验证不应修改仓库内任何文件。小结TOP001 是 cu/curriculum 仓库 Markdown 质量体系中的第一条自定义规则它以“链接文本必须自带描述性”为宗旨通过独立单词 this/here 检测与 22 词黑名单精确匹配两道机制把可访问性要求固化为可自动执行的 lint 检查。测试夹具 this_or_here.md 与 blacklisted_label_text.md 不仅验证了规则的正确行为也精确记录了边界情况子串不误报、长文本不误报、同页多链接逐条报错、有意的误报场景。理解这套检测逻辑既能帮助你写出更符合规范、更利于辅助技术用户理解的 Markdown 文档也能为在同类内容仓库中设计与维护自定义 lint 规则提供可直接复用的参考范式。【免费下载链接】curriculumThe open curriculum for learning web development项目地址: https://gitcode.com/GitHub_Trending/cu/curriculum创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 curriculum 仓库 Markdown 链接规范实战：TOP001 描述性链接文本检测规则解析
curriculum 仓库 Markdown 链接规范实战TOP001 描述性链接文本检测规则解析【免费下载链接】curriculumThe open curriculum for learning web development项目地址: https://gitcode.com/GitHub_Trending/cu/curriculum本指南围绕开源课程仓库 cu/curriculum 中自研的 Markdown 静态检查规则TOP001descriptive-link-text-labels展开重点以测试用例 this_or_here.md 与 blacklisted_label_text.md 为切入点讲清楚该规则“什么会被标记、什么不会被标记、为什么”并结合 规则源码 与 单元测试 还原其检测原理。读完你将掌握描述性链接文本的编写标准、该规则的判定边界与误报场景以及如何在本地运行 lint 与测试验证。规则背景为什么链接文本必须“可描述”TOP001 规则的完整定义与设计动机记录在 规则文档 中其标签为accessibility与links别名descriptive-link-text-labels。它服务的核心场景是当文档中的链接文本本身无法让读者尤其是使用屏幕阅读器等辅助技术的用户理解链接指向的内容时该规则将触发告警。这背后的可访问性原理是辅助技术用户经常通过“跳转链接列表”来浏览页面此时链接文本被脱离上下文单独朗读。像here或click this这样的文本在脱离上下文后完全没有信息量而像video、docs这类文本虽然包含一个名词但同样无法让用户预判目标内容。因此课程仓库要求链接文本“本身就足够描述性”这正是 TOP001 要强制落实的规范。规则触发条件两种被标记的链接文本依据 TOP001 规则文档 与 规则源码链接满足以下任一条件即触发错误链接文本中包含单词 “this” 或 “here”不区分大小写且要求是独立单词详见下文“词边界”小节链接文本整体精确命中黑名单词条——即文本内容不包含 this/here但本身过于笼统例如 “video”“article”“docs”“documentation”“homepage” 等。两条规则分别对应两种不同的错误详情提示命中 this/here 时提示Expected text to not include the words this or here. Use a more descriptive label that clearly conveys the purpose or content of the link.命中黑名单时提示文本 is not sufficiently descriptive by itself. Use a more descriptive label that clearly conveys the purpose or content of the link.测试用例之一this_or_here.md 的判定边界this_or_here.md 是一份“只包含该规则违规、不包含其他规则违规”的专用测试夹具测试文件规范见 docs/README.md。它将链接分为两组直观展示了规则的判定边界。不应被标记的链接合法正例Some descriptive link text He replied With is Where Heresy Some text with the word video Some text with the words documentation, an article, docs, the docs, page, a video, articles, resource, their docs这些链接之所以合法原因有三He replied中的 “replied” 只是含 “here” 的字母串并非单词 “here”Where、Heresy同理仅包含 “here” 子串Some text with the word video这类文本中虽然出现了黑名单词 “video”“docs”“page” 等但黑名单要求整个链接文本精确匹配长文本不构成命中。应被标记的链接违规反例this This video here Click here This other thing This blog post about flex-grow will be flagged as a false positive, but could still be updated This will get caught and so will this as separate matches这些链接全部因为包含独立单词 “this” 或 “here” 而被标记。注意两个细节This video开头的大写 “This” 同样会被捕获正则开启了i忽略大小写标志[This blog post about flex-grow will be flagged as a false positive...]是规则的有意误报false positive即使文本主体相当描述性只要出现了 “this” 一词规则依然会标记因为辅助技术用户跳读链接时 “This...” 的指代性依然不明确。测试用例之二blacklisted_label_text.md 的精确匹配blacklisted_label_text.md 展示的是黑名单机制链接文本整体命中黑名单词条时被标记例如video videos a video docs the documentation their documentation page their homepage playlist a playlist注意匹配方式源码中调用的是BLACKLISTED_LINK_TEXT.includes(linkContentString.toLowerCase())即把链接文本转小写后做数组精确查找而不是子串匹配。因此a video命中词条a video而Some text with the word video不命中。完整黑名单清单以下 22 个词条定义在 规则源码 的BLACKLISTED_LINK_TEXT数组中video, videos, a video, playlist, a playlist, article, articles, an article, doc, docs, the docs, their docs, documentation, the documentation, their documentation, resource, library, page, homepage, the homepage, their homepage,这些词条的共同特征是它们是“媒体/内容类型名词”或“泛指代词”单独作为链接文本无法传达目标内容。源码实现从 Token 流到正则判定TOP001 是一个基于markdownit解析器的自定义规则项目要求所有自定义规则的parser字段必须为markdownit见 docs/README.md。核心实现位于 TOP001_descriptiveLinkTextLabels.js处理流程如下筛选含链接的 Token从params.parsers.markdownit.tokens中过滤出子节点里存在link_open的 token定位链接文本区间对每个link_opentoken在其后续子节点中查找link_close的位置中间夹着的就是链接文本的 token 序列还原链接文本字符串遍历文本 token 并拼接其中code_inline类型会加上反引号包裹\${token.content}使行内代码的语义被保留双重判定用正则/.*?(?!(\w|))(this|here)(?!(\w|)).*?/i检测是否包含独立单词 this/here将拼接出的文本toLowerCase()后与黑名单数组做includes精确匹配上报错误命中任一条件即调用onError输出行号、详情与文本形式的上下文。词边界正则的细节判定 this/here 的正则/.*?(?!(\w|))(this|here)(?!(\w|)).*?/i使用了负向零宽断言来实现“独立单词”匹配(?!(\w|)) 保证 this/here 之前不是字母、数字、下划线或反引号(?!(\w|)) 保证之后也不是字母、数字、下划线或反引号结尾的i标志使其大小写不敏感。这正是He replied、Where、Heresy不会被误报的原因——replied/Where/Heresy中的here子串前后都紧邻字母不符合词边界要求。源码注释还提供了 regexr.com/7sdtj 作为在线验证工具。测试如何验证断言驱动的回归保障规则的所有行为都由 Node 内置测试运行器node --test驱动验证见 TOP001.test.js。该测试文件通过getLintErrors工具对两份测试夹具执行真实的 lint 命令并逐一断言错误输出对./this_or_here.md断言产生8 条错误依次对应第 23、24、25、26、27、28 行以及第 29 行同一行内的两条独立链接[This will get caught]与[this as separate matches]每条错误都包含规则名、描述与Context: [this]形式的上下文对./blacklisted_label_text.md断言产生10 条错误覆盖第 2332 行的全部黑名单链接另外测试还验证规则对象的information字段正确指向规则文档。其中getLintErrors的实现位于 test_utils/lint.js它对目标文件执行npm run lint -- 文件路径若命令以非零码退出则把stderr按行拆分后作为错误数组返回若退出码为 0无违规则返回空数组。这种“以真实 CLI 输出作为断言依据”的方式保证了测试与生产 lint 行为完全一致。如何修复把 this/here 和笼统名词改写成具体内容规则文档 TOP001.md 给出了修复原则删除 “here”“this”改用能清楚传达链接目的或内容的文本必要时同步改写周围句子。例如# 违规 You can read more about variables in JavaScript [here](https://example.com). [This article](https://example.com) provides more information about closures. # 修复 You can read more about [variables in JavaScript](https://example.com). [An in-depth article about closures in JavaScript](https://example.com) provides more information.即使文本本身已有一定描述性只要包含 this/here 仍会被标记因此也要改写# 违规仍会命中 this [Here is a comprehensive guide to understanding closures](https://example.com). # 修复 [Comprehensive guide to understanding closures](https://example.com)对于黑名单命中的笼统名词修复思路是在链接文本中补充具体主题关键词# 违规 For more information, watch this [video](https://example.com) about the CSS box model. You can read more about it in the [documentation](https://example.com). # 修复 For more information, watch this [video about the CSS box model](https://example.com). You can read more about it in the [Proc class documentation](https://example.com).本地运行与验证本仓库通过 package.json 暴露三条命令依赖markdownlint-cli2npm run lint执行markdownlint-cli2对仓库 Markdown 文件做静态检查TOP001 属于其中一条自定义规则npm run fix执行markdownlint-cli2 --fix自动修复可修复项TOP001 因依赖上下文语义文档明确标注不可自动修复即Fixable via script: Not fixable due to being context-basednpm run test执行node --test运行全部自定义规则测试其中就包含 TOP001.test.js 对两份测试夹具的断言。若只想单独观察 TOP001 的报错效果可以对测试夹具直接跑 lint例如对this_or_here.md执行检查会得到包含行号、规则名、错误详情与链接上下文的多行错误输出。需要注意的是本仓库为只读资源上述命令仅用于本地查看与验证不应修改仓库内任何文件。小结TOP001 是 cu/curriculum 仓库 Markdown 质量体系中的第一条自定义规则它以“链接文本必须自带描述性”为宗旨通过独立单词 this/here 检测与 22 词黑名单精确匹配两道机制把可访问性要求固化为可自动执行的 lint 检查。测试夹具 this_or_here.md 与 blacklisted_label_text.md 不仅验证了规则的正确行为也精确记录了边界情况子串不误报、长文本不误报、同页多链接逐条报错、有意的误报场景。理解这套检测逻辑既能帮助你写出更符合规范、更利于辅助技术用户理解的 Markdown 文档也能为在同类内容仓库中设计与维护自定义 lint 规则提供可直接复用的参考范式。【免费下载链接】curriculumThe open curriculum for learning web development项目地址: https://gitcode.com/GitHub_Trending/cu/curriculum创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考