Super Productivity 文档质量保障指南Wiki 链接校验与 Markdown Lint 的 CI 落地实践【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity导读本篇指南围绕 Super Productivity 仓库中 Wiki 文档的质量保障机制展开核心回答两个问题如何在提交 PR 前本地校验 Wiki 文档以及CI 如何自动完成 Markdown lint 与本地链接检查。读完本文你将掌握npm run docs:check-links与pymarkdownlnt两条命令的完整用法、链接检查器支持与拒绝的语法细节以及文档源引用source citation的静默腐化问题与解决方案可以直接复用于任何以文档为交付物的仓库。关联文档位于 docs/wiki/0.02-Wiki-QA-and-Maintenance.md它是 Wiki 维护流程的验收关卡定义文档配套的实现与测试则散落在 tools/check-doc-links.js、tools/check-doc-links.test.js 与两个 CI 工作流文件中。Wiki 文档为何需要专门的 QA 流程Super Productivity 的 Wiki 是一份人工精心维护、面向人类读者的文档集存放于docs/wiki/目录会通过 CI 自动同步到 GitHub Wiki见 .github/workflows/wiki-sync.yml 中的 rsync 硬镜像步骤。既然文档会被自动化管线搬运就必须保证搬运前后的格式兼容文档同时面向CommonMark、GitHub Flavored Markdown、GitHub 内置 Wiki 限制与 Obsidian 风格 Markdown四种渲染环境某些语法在其中一种环境下可用、在另一种环境下却会解析失败GitHub Wiki 会对收到的文件做命名整理与结构重构例如将空格替换为短横线、折叠子目录中的同名笔记路径与命名一旦踩线就会静默失效文档数量庞大、交叉引用密集链接一旦失效读者点击后得到 404靠人工逐一核查成本极高。因此仓库在 CI 中同时挂了Markdown 语法 lint与本地链接校验两道关卡docs/wiki/0.02-Wiki-QA-and-Maintenance.md 就是这道关卡的使用说明。提交前必须运行的两条命令命令一本地链接校验零第三方依赖npm run docs:check-links该脚本定义在根目录 package.json 的docs:check-links字段实际执行node ./tools/check-doc-links.js docs。实现文件 tools/check-doc-links.js不依赖任何第三方 npm 包仅使用 Node.js 内置模块fs、path因此即便在不安装依赖的干净环境中也能运行——这是它在 CI 中作为 PR 门槛的前提条件之一。脚本默认从docs目录出发递归收集所有文档.md、.markdown、.html、.htm逐行提取链接目标并校验。校验通过时输出Documentation links are valid.并以退出码 0 结束发现问题时输出形如以下的行并以退出码 1 结束docs/wiki/foo.md:12: missing link target bar.md docs/wiki/foo.md:15: missing anchor guide.md#usage命令二Markdown lintCI 必选、本地可选pymarkdownlnt --disable-rules line-length,no-inline-html scan docs/wikipymarkdownlnt是 Python 生态的 Markdown lint 工具。原文档明确指出它本地可选、CI 必需本地开发者可以只跑链接检查但 CI 的 Wiki 同步工作流会强制执行 lint。命令中两个被禁用的规则值得说明line-lengthWiki 页面中存在大量超长代码示例与表格行长度规则会导致大量误报no-inline-htmlWiki 使用 HTML 注释作为 lint 指令见下文 MD041 豁免机制因此需要放行内联 HTML。在 .github/workflows/wiki-sync.yml 的lintjob 中可以看到完全一致的调用pymarkdownlnt --disable-rules line-length,no-inline-html scan docs/wiki且该 job 运行在setup-python提供的 Python 3.13 环境中依赖通过pip install yamllint pymarkdownlnt安装。进阶用法在 docs/wiki/0.01-Style-Guide.md 中记录了将pymarkdownlnt配置为 git pre-commit 钩子的方式确保每次提交都能在本地提前暴露 lint 问题而不是等到 CI 才失败。链接检查器的完整语法覆盖链接检查器并非简单正则匹配tools/check-doc-links.js 实现了相当完整的 Markdown 解析逻辑了解它能检查什么、忽略什么才能避免写出本地通过、CI 通过、实际却 404的链接。支持检查的链接类型类型示例校验内容Markdown 链接指南目标文件存在 #anchor存在Markdown 图片截图图片文件存在HTMLhref/srca hrefpage.html#details目标文件 锚点存在锚点自引用[本节](#current-section)当前文件内存在该锚点Wiki 链接[[Wiki-Page]]、[[assets/img.png]]目标笔记/图片存在从源文档所在目录解析源代码中的docs/**引用注释// See docs/guide.md目标文档存在第二遍扫描被正确忽略的内容检查器刻意忽略以下伪链接避免误报外部 URLhttps://、mailto:、//开头等协议目标一律跳过EXTERNAL_TARGET正则行内代码与代码围栏fake和 fenced block 内的链接不算数HTML 注释中的锚点被注释掉的div id...不会成为有效锚点。值得注意的严格规则Wiki 链接别名一律拒绝[[可读标签|Guide]]这类带|的别名会被报告为unsupported wiki-link alias。原文档给出的原因是GitHub 会把该语法渲染成../wiki/Test-Note之类的 URL指向不存在的路径——这也是 docs/wiki/0.01-Style-Guide.md 明确禁止的写法。仓库边界防护../outside.md这类逃逸出仓库根的相对路径以及通过符号链接指向仓库外的文件都会被标记为link target escapes repository。这保证了链接校验的结果对 GitHub Wiki 环境同样成立。锚点按渲染后文本计算标题锚点会先剥离 Markdown 链接、下划线强调与 HTML 标签再生成 slug。测试 tools/check-doc-links.test.js 中的matches rendered heading text and resolves cross-slug collisions用例验证了# _Emphasized setup_这类标题会被解析为emphasized-setup且重名标题会依次追加-1、-2后缀。单文件限制文档超过 1 MiBMAX_DOCUMENT_BYTES或单行超过 16 KiBMAX_LINE_LENGTH会被报告为问题防止异常大文件拖慢检查诊断信息最多输出 100 条MAX_DIAGNOSTICS但总数仍会如实报告。第二遍扫描源代码中的文档引用tools/check-doc-links.js 还实现了一个其他仓库少见的检查扫描.ts、.tsx、.js、.kt、.java、.swift、.scss、.yaml、.sh等源码文件查找注释中出现的docs/**路径DOCS_PATH_IN_SOURCE正则并验证目标文档是否真实存在。其设计动机在源码注释中写得很清楚Source files cite documents in comments… a deleted doc leaves dangling pointers that no check can see——文档扫描永远不会打开.ts文件所以被删除的文档会在源码注释里留下无法察觉的悬空引用。第二遍扫描的解析策略是同一路径同时尝试仓库根与最近的 package 目录两种基准一个位于packages/foo/下的注释可能指的是packages/foo/docs/bar.md跳过node_modules、dist、coverage、.git等目录同一文件对同一目标的多次引用只报告一次避免噪音。该逻辑对应的测试用例见 tools/check-doc-links.test.js 的reports docs paths cited from source comments when the file is missing与resolves source-cited docs paths against the nearest enclosing package。CI 如何组织这两类检查文档链接工作流.github/workflows/docs-links.yml该工作流在 PR 与 master/main 分支的 push 上运行仅需 Node.js 22不安装任何 npm 依赖。三个步骤各有分工# 1. 运行检查器自身的单元测试确保工具本身可信 node --test tools/check-doc-links.test.js # 2. 对 git 追踪的所有 Markdown 文件做文档链接检查 # xargs 可能分批调用脚本因此用 --docs-only 避免重复做源码扫描 git ls-files -z -- *.md *.markdown | xargs -0 -r node tools/check-doc-links.js --docs-only # 3. HTML 文档单独一批docs/ 与 packages/**/docs/ 下 git ls-files -z -- \ :(glob)docs/**/*.html \ :(glob)packages/**/docs/**/*.html | xargs -0 -r node tools/check-doc-links.js --docs-only # 4. 源码注释引用单独跑一次避免每批都重复扫描 node tools/check-doc-links.js --sources-only--docs-only与--sources-only两个 CLI 标志就是为这套批量调用设计的文档检查可以随xargs分批执行而源码引用扫描必须全局去重、只跑一次。Wiki 同步工作流.github/workflows/wiki-sync.yml该工作流仅在docs/wiki/**相关文件变更时触发包含lint与sync两个 joblint job先以yamllint校验工作流自身的 YAML 格式针对 SHA 固定版本注释放宽行长度到 120再以pymarkdownlnt --disable-rules line-length,no-inline-html扫描整个docs/wikilint 失败则整个工作流中断sync job仅在 push 事件上运行needs: lint保证只有通过 lint 的内容才会被同步。同步方式为rsync 硬镜像——--archive --delete --prune-empty-dirs组合意味着docs/wiki永远是 GitHub Wiki 的唯一事实来源Wiki 端被删除的文件会被清除空目录会被裁剪。对贡献者而言这意味着Wiki 的校验发生在 PR 阶段docs-links.yml wiki-sync.yml 的 lint发布发生在合入主分支之后sync job。为什么外部 URL 不做自动化检查原文档明确说明外部 URL 不会被自动爬取。原因有两层临时性网络故障会让 PR 门槛不稳定外部站点的一次 5xx 或超时就会让一个内容完全正确的 PR 被标红把链接检查变成运气测试外部链接的生命周期本质上是慢失效它不会在内容变更的瞬间破裂而是在数月或数年后静默失效因此不适合放在即时反馈的 PR 门禁中。配套的替代策略是人工纪律 可能的定期报告每新增或修改一个外部链接打开并确认其可达优先选择稳定的第一手来源官方文档、规范原文而不是聚合页发现死链时替换为仍在维护的来源而不是换成另一个聚合器原文档提到可能单独添加定时外部链接报告前提是它能区分暂时性故障与永久性失效——这种区分能力决定了自动化是否可行。把这一套机制迁移到自己的仓库从 Super Productivity 的实现中可提炼出四步通用方案自带链接检查器零依赖的 Node 脚本如 tools/check-doc-links.js比引入重量级框架更适合作为 CI 门槛——安装开销为零、失败面最小文档与源码双通道校验既检查文档内部的链接也检查源码注释对docs/**路径的引用堵住文档被删、注释悬空的静默腐化路径lint 与链接检查分工语法规范用pymarkdownlntCI 强制路径正确性用链接检查器二者互补而非重复CI 分批与去重通过--docs-only/--sources-only之类的标志让批量调用的任务各自只负责一个职责避免重复扫描带来的 O(n²) 开销与重复诊断。对应地可运行node --test tools/check-doc-links.test.js复现仓库中 20 余个测试用例作为理解检查器边界行为的活文档docs/README.md 的 Review checklist 也把npm run docs:check-links列为文档变更的最终验证步骤。小结Super Productivity 的 Wiki QA 机制可以概括为一张双层防线语法层pymarkdownlnt禁用line-length与no-inline-html保证所有 Wiki 笔记能被 CommonMark / GFM / Obsidian 兼容解析由 .github/workflows/wiki-sync.yml 强制结构层零依赖链接检查器npm run docs:check-links保证 Markdown 链接、HTML 属性、图片、Wiki 链接与源码注释引用全部可达由 .github/workflows/docs-links.yml 在 PR 阶段执行发布层通过 lint 的内容在合入主分支后经 rsync 硬镜像到 GitHub Wiki保证线上 Wiki 与仓库docs/wiki永远一致。对于贡献者来说提交 Wiki 变更前的完整自检序列就是npm run docs:check-links确认链接无破损再运行pymarkdownlnt --disable-rules line-length,no-inline-html scan docs/wiki确认语法合规最后人工确认新增的外部链接指向稳定的一手来源。这套机制让大规模文档仓库的维护从靠人肉巡检进化到提交即校验。【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Super Productivity 文档质量保障指南：Wiki 链接校验与 Markdown Lint 的 CI 落地实践
Super Productivity 文档质量保障指南Wiki 链接校验与 Markdown Lint 的 CI 落地实践【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity导读本篇指南围绕 Super Productivity 仓库中 Wiki 文档的质量保障机制展开核心回答两个问题如何在提交 PR 前本地校验 Wiki 文档以及CI 如何自动完成 Markdown lint 与本地链接检查。读完本文你将掌握npm run docs:check-links与pymarkdownlnt两条命令的完整用法、链接检查器支持与拒绝的语法细节以及文档源引用source citation的静默腐化问题与解决方案可以直接复用于任何以文档为交付物的仓库。关联文档位于 docs/wiki/0.02-Wiki-QA-and-Maintenance.md它是 Wiki 维护流程的验收关卡定义文档配套的实现与测试则散落在 tools/check-doc-links.js、tools/check-doc-links.test.js 与两个 CI 工作流文件中。Wiki 文档为何需要专门的 QA 流程Super Productivity 的 Wiki 是一份人工精心维护、面向人类读者的文档集存放于docs/wiki/目录会通过 CI 自动同步到 GitHub Wiki见 .github/workflows/wiki-sync.yml 中的 rsync 硬镜像步骤。既然文档会被自动化管线搬运就必须保证搬运前后的格式兼容文档同时面向CommonMark、GitHub Flavored Markdown、GitHub 内置 Wiki 限制与 Obsidian 风格 Markdown四种渲染环境某些语法在其中一种环境下可用、在另一种环境下却会解析失败GitHub Wiki 会对收到的文件做命名整理与结构重构例如将空格替换为短横线、折叠子目录中的同名笔记路径与命名一旦踩线就会静默失效文档数量庞大、交叉引用密集链接一旦失效读者点击后得到 404靠人工逐一核查成本极高。因此仓库在 CI 中同时挂了Markdown 语法 lint与本地链接校验两道关卡docs/wiki/0.02-Wiki-QA-and-Maintenance.md 就是这道关卡的使用说明。提交前必须运行的两条命令命令一本地链接校验零第三方依赖npm run docs:check-links该脚本定义在根目录 package.json 的docs:check-links字段实际执行node ./tools/check-doc-links.js docs。实现文件 tools/check-doc-links.js不依赖任何第三方 npm 包仅使用 Node.js 内置模块fs、path因此即便在不安装依赖的干净环境中也能运行——这是它在 CI 中作为 PR 门槛的前提条件之一。脚本默认从docs目录出发递归收集所有文档.md、.markdown、.html、.htm逐行提取链接目标并校验。校验通过时输出Documentation links are valid.并以退出码 0 结束发现问题时输出形如以下的行并以退出码 1 结束docs/wiki/foo.md:12: missing link target bar.md docs/wiki/foo.md:15: missing anchor guide.md#usage命令二Markdown lintCI 必选、本地可选pymarkdownlnt --disable-rules line-length,no-inline-html scan docs/wikipymarkdownlnt是 Python 生态的 Markdown lint 工具。原文档明确指出它本地可选、CI 必需本地开发者可以只跑链接检查但 CI 的 Wiki 同步工作流会强制执行 lint。命令中两个被禁用的规则值得说明line-lengthWiki 页面中存在大量超长代码示例与表格行长度规则会导致大量误报no-inline-htmlWiki 使用 HTML 注释作为 lint 指令见下文 MD041 豁免机制因此需要放行内联 HTML。在 .github/workflows/wiki-sync.yml 的lintjob 中可以看到完全一致的调用pymarkdownlnt --disable-rules line-length,no-inline-html scan docs/wiki且该 job 运行在setup-python提供的 Python 3.13 环境中依赖通过pip install yamllint pymarkdownlnt安装。进阶用法在 docs/wiki/0.01-Style-Guide.md 中记录了将pymarkdownlnt配置为 git pre-commit 钩子的方式确保每次提交都能在本地提前暴露 lint 问题而不是等到 CI 才失败。链接检查器的完整语法覆盖链接检查器并非简单正则匹配tools/check-doc-links.js 实现了相当完整的 Markdown 解析逻辑了解它能检查什么、忽略什么才能避免写出本地通过、CI 通过、实际却 404的链接。支持检查的链接类型类型示例校验内容Markdown 链接指南目标文件存在 #anchor存在Markdown 图片截图图片文件存在HTMLhref/srca hrefpage.html#details目标文件 锚点存在锚点自引用[本节](#current-section)当前文件内存在该锚点Wiki 链接[[Wiki-Page]]、[[assets/img.png]]目标笔记/图片存在从源文档所在目录解析源代码中的docs/**引用注释// See docs/guide.md目标文档存在第二遍扫描被正确忽略的内容检查器刻意忽略以下伪链接避免误报外部 URLhttps://、mailto:、//开头等协议目标一律跳过EXTERNAL_TARGET正则行内代码与代码围栏fake和 fenced block 内的链接不算数HTML 注释中的锚点被注释掉的div id...不会成为有效锚点。值得注意的严格规则Wiki 链接别名一律拒绝[[可读标签|Guide]]这类带|的别名会被报告为unsupported wiki-link alias。原文档给出的原因是GitHub 会把该语法渲染成../wiki/Test-Note之类的 URL指向不存在的路径——这也是 docs/wiki/0.01-Style-Guide.md 明确禁止的写法。仓库边界防护../outside.md这类逃逸出仓库根的相对路径以及通过符号链接指向仓库外的文件都会被标记为link target escapes repository。这保证了链接校验的结果对 GitHub Wiki 环境同样成立。锚点按渲染后文本计算标题锚点会先剥离 Markdown 链接、下划线强调与 HTML 标签再生成 slug。测试 tools/check-doc-links.test.js 中的matches rendered heading text and resolves cross-slug collisions用例验证了# _Emphasized setup_这类标题会被解析为emphasized-setup且重名标题会依次追加-1、-2后缀。单文件限制文档超过 1 MiBMAX_DOCUMENT_BYTES或单行超过 16 KiBMAX_LINE_LENGTH会被报告为问题防止异常大文件拖慢检查诊断信息最多输出 100 条MAX_DIAGNOSTICS但总数仍会如实报告。第二遍扫描源代码中的文档引用tools/check-doc-links.js 还实现了一个其他仓库少见的检查扫描.ts、.tsx、.js、.kt、.java、.swift、.scss、.yaml、.sh等源码文件查找注释中出现的docs/**路径DOCS_PATH_IN_SOURCE正则并验证目标文档是否真实存在。其设计动机在源码注释中写得很清楚Source files cite documents in comments… a deleted doc leaves dangling pointers that no check can see——文档扫描永远不会打开.ts文件所以被删除的文档会在源码注释里留下无法察觉的悬空引用。第二遍扫描的解析策略是同一路径同时尝试仓库根与最近的 package 目录两种基准一个位于packages/foo/下的注释可能指的是packages/foo/docs/bar.md跳过node_modules、dist、coverage、.git等目录同一文件对同一目标的多次引用只报告一次避免噪音。该逻辑对应的测试用例见 tools/check-doc-links.test.js 的reports docs paths cited from source comments when the file is missing与resolves source-cited docs paths against the nearest enclosing package。CI 如何组织这两类检查文档链接工作流.github/workflows/docs-links.yml该工作流在 PR 与 master/main 分支的 push 上运行仅需 Node.js 22不安装任何 npm 依赖。三个步骤各有分工# 1. 运行检查器自身的单元测试确保工具本身可信 node --test tools/check-doc-links.test.js # 2. 对 git 追踪的所有 Markdown 文件做文档链接检查 # xargs 可能分批调用脚本因此用 --docs-only 避免重复做源码扫描 git ls-files -z -- *.md *.markdown | xargs -0 -r node tools/check-doc-links.js --docs-only # 3. HTML 文档单独一批docs/ 与 packages/**/docs/ 下 git ls-files -z -- \ :(glob)docs/**/*.html \ :(glob)packages/**/docs/**/*.html | xargs -0 -r node tools/check-doc-links.js --docs-only # 4. 源码注释引用单独跑一次避免每批都重复扫描 node tools/check-doc-links.js --sources-only--docs-only与--sources-only两个 CLI 标志就是为这套批量调用设计的文档检查可以随xargs分批执行而源码引用扫描必须全局去重、只跑一次。Wiki 同步工作流.github/workflows/wiki-sync.yml该工作流仅在docs/wiki/**相关文件变更时触发包含lint与sync两个 joblint job先以yamllint校验工作流自身的 YAML 格式针对 SHA 固定版本注释放宽行长度到 120再以pymarkdownlnt --disable-rules line-length,no-inline-html扫描整个docs/wikilint 失败则整个工作流中断sync job仅在 push 事件上运行needs: lint保证只有通过 lint 的内容才会被同步。同步方式为rsync 硬镜像——--archive --delete --prune-empty-dirs组合意味着docs/wiki永远是 GitHub Wiki 的唯一事实来源Wiki 端被删除的文件会被清除空目录会被裁剪。对贡献者而言这意味着Wiki 的校验发生在 PR 阶段docs-links.yml wiki-sync.yml 的 lint发布发生在合入主分支之后sync job。为什么外部 URL 不做自动化检查原文档明确说明外部 URL 不会被自动爬取。原因有两层临时性网络故障会让 PR 门槛不稳定外部站点的一次 5xx 或超时就会让一个内容完全正确的 PR 被标红把链接检查变成运气测试外部链接的生命周期本质上是慢失效它不会在内容变更的瞬间破裂而是在数月或数年后静默失效因此不适合放在即时反馈的 PR 门禁中。配套的替代策略是人工纪律 可能的定期报告每新增或修改一个外部链接打开并确认其可达优先选择稳定的第一手来源官方文档、规范原文而不是聚合页发现死链时替换为仍在维护的来源而不是换成另一个聚合器原文档提到可能单独添加定时外部链接报告前提是它能区分暂时性故障与永久性失效——这种区分能力决定了自动化是否可行。把这一套机制迁移到自己的仓库从 Super Productivity 的实现中可提炼出四步通用方案自带链接检查器零依赖的 Node 脚本如 tools/check-doc-links.js比引入重量级框架更适合作为 CI 门槛——安装开销为零、失败面最小文档与源码双通道校验既检查文档内部的链接也检查源码注释对docs/**路径的引用堵住文档被删、注释悬空的静默腐化路径lint 与链接检查分工语法规范用pymarkdownlntCI 强制路径正确性用链接检查器二者互补而非重复CI 分批与去重通过--docs-only/--sources-only之类的标志让批量调用的任务各自只负责一个职责避免重复扫描带来的 O(n²) 开销与重复诊断。对应地可运行node --test tools/check-doc-links.test.js复现仓库中 20 余个测试用例作为理解检查器边界行为的活文档docs/README.md 的 Review checklist 也把npm run docs:check-links列为文档变更的最终验证步骤。小结Super Productivity 的 Wiki QA 机制可以概括为一张双层防线语法层pymarkdownlnt禁用line-length与no-inline-html保证所有 Wiki 笔记能被 CommonMark / GFM / Obsidian 兼容解析由 .github/workflows/wiki-sync.yml 强制结构层零依赖链接检查器npm run docs:check-links保证 Markdown 链接、HTML 属性、图片、Wiki 链接与源码注释引用全部可达由 .github/workflows/docs-links.yml 在 PR 阶段执行发布层通过 lint 的内容在合入主分支后经 rsync 硬镜像到 GitHub Wiki保证线上 Wiki 与仓库docs/wiki永远一致。对于贡献者来说提交 Wiki 变更前的完整自检序列就是npm run docs:check-links确认链接无破损再运行pymarkdownlnt --disable-rules line-length,no-inline-html scan docs/wiki确认语法合规最后人工确认新增的外部链接指向稳定的一手来源。这套机制让大规模文档仓库的维护从靠人肉巡检进化到提交即校验。【免费下载链接】super-productivitySuper Productivity is an advanced todo list app with integrated Timeboxing and time tracking capabilities. It also comes with integrations for Jira, GitLab, GitHub and Open Project.项目地址: https://gitcode.com/GitHub_Trending/su/super-productivity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考