docs-site 高 ROI 功能头脑风暴
名词定义
站点构件
- docs-site：本仓库
docs-site/下基于 Docusaurus 3 的静态文档站，文档源挂../docs/。 - generated-*.json：6 个构建时生成的映射文件（节编号 / 公式偏移 / 公式 label / 图 label / 表 label / 文档路由），由
gen-sidebars.mjs产出，当前被 git 跟踪。 - clientModules：Docusaurus 浏览器端运行的脚本，本站有 6 个（大纲折叠 / MathJax 排版 / 节编号 / 图注 / lightbox / 记忆阅读位置）。
业界工具
- MkDocs Material：Python 系最流行的文档站主题，内置 tags / social cards / 分级链接校验。
- docusaurus-graph：社区插件，把文档间链接关系渲染为可交互关系图。
- Obsidian Publish：Obsidian 笔记发布服务，以 backlinks（反向链接）和 hover preview（悬停预览）著称。
方法
- RICE：收敛打分法，分 = Reach × Impact × Confidence / Effort。
现状盘点
docs-site 已具备的能力：
| 能力 | 实现 |
|---|---|
| 自动侧边栏 / 导航栏 | gen-sidebars.mjs 扫描 docs/ 生成 |
章节 / 公式 / 图表编号，跨文件 \eqref 跳转 | 6 个 generated-*.json + 内联 remark 插件 |
| footnote → 参考资料节自动聚合 | remark 插件 processFootnotes |
| 链接文本自动改写为目标文档标题 | remark 插件，带节编号前缀 |
| 本地中英文搜索 | @easyops-cn/docusaurus-search-local |
| mermaid 图编号 / 图注 / lightbox / 记忆阅读位置 | clientModules |
| 文档重命名联动改引用 | rename-doc.mjs |
现存痛点：
- 引用校验形同虚设：
onBrokenLinks: 'warn'、onBrokenAnchors: 'ignore'，坏链和悬空 label 不挡构建。 - MathJax 依赖外网 CDN：jsdelivr 挂掉或内网环境下公式全站不可用，且是首屏延迟来源。
- generated JSON 进 git：每次文档变更产生 6 条 diff 噪音。
候选清单（按维度）
内容质量保障
- ref-integrity-check — 构建时校验引用完整性：坏链转 throw、
\eqref/figref 悬空 label 报错。 - docs-lint-ci — docs-conventions 机械规则（H2 禁手动编号 / 图表必须有 label）做成 lint 脚本进 CI。
- generated-map-staleness-check — 校验 generated-*.json 与 docs/ 实际状态一致。
检索与发现
- global-index-pages — 自动生成全站图表 / 公式 / 术语索引页。
- search-tuning — 中文搜索质量调优（标题加权、分词）。
- related-docs — 页面底部相关文档推荐（基于链接结构）。
知识网络
- backlinks-panel — 每页底部显示被哪些文档引用（doc-route-map 反转即得）。
- graph-view — 文档关系图（现成插件 docusaurus-graph）。
- tags-taxonomy — frontmatter tags + 标签聚合页。
阅读体验
- mathjax-local — MathJax 从 CDN 改为本地打包。
- link-hover-preview — 悬停内链显示目标文档摘要。
- per-doc-pdf — 单篇 / 单章 PDF 导出。
作者工作流
- new-doc-scaffold — 新文档脚手架：按 docs-conventions 模板生成骨架 + frontmatter。
- rename-dir-support —
rename-doc.mjs扩展到目录级重命名。 - label-dup-check — label 重复检测。
发布与离线
- offline-bundle — 全离线构建（MathJax + 字体本地化），内网可部署。
工程健康
- generated-json-out-of-git — generated-*.json 移出 git，构建时生成。
- config-plugin-extract — docusaurus.config.ts 内联 remark 插件（约 300 行）抽独立模块 + 单测。
- gen-sidebars-refactor — 28K 的 gen-sidebars.mjs 拆分。
业界对标
| 工具 | 启发 / 印证 |
|---|---|
| MkDocs Material | tags 体系、social cards、链接校验分 warn/info/ignore 级 |
| Docusaurus 社区插件目录 | docusaurus-graph 关系图、papersaurus / prince-pdf PDF 导出 |
| Docusaurus 核心 | broken anchors 检测已内置，ref-integrity-check 大半是改配置而非写代码 |
social cards 面向社交分享，对内部站无意义，不回填。
收敛矩阵（RICE）
R=受益频率(0-10)，I=影响(0.25-3)，C=信心(0-1)，E=人周。分 = R×I×C/E。
| 候选 | R | I | C | E | 分 | 理由 |
|---|---|---|---|---|---|---|
| generated-json-out-of-git | 8 | 1 | 1.0 | 0.2 | 40 | 每次 commit 受益；纯构建脚本改动，零风险 |
| mathjax-local | 9 | 1.5 | 0.9 | 0.3 | 40 | 每次打开页面受益；去掉外网单点依赖 |
| ref-integrity-check | 10 | 2 | 0.9 | 0.5 | 36 | 每次构建拦截腐烂；本站核心价值是交叉引用网 |
| new-doc-scaffold | 5 | 1.5 | 0.9 | 0.5 | 13.5 | 每写新文档受益，与 iforge-research 衔接 |
| backlinks-panel | 7 | 2 | 0.8 | 1 | 11.2 | 知识库刚需，数据已有只差 UI |
| docs-lint-ci | 6 | 2 | 0.8 | 1 | 9.6 | 把 review skill 机械检查左移到构建时 |
| link-hover-preview | 7 | 1.5 | 0.7 | 1.5 | 4.9 | 体验好但需摘要提取 + 浮层组件 |
| graph-view | 3 | 1 | 0.7 | 0.5 | 4.2 | 现成插件便宜，观赏多于实用 |
| config-plugin-extract | 2 | 1 | 0.9 | 0.5 | 3.6 | 维护性收益，需单测保护编号系统 |
| global-index-pages | 4 | 1 | 0.8 | 1 | 3.2 | 锦上添花 |
| tags-taxonomy | 3 | 1 | 0.8 | 1 | 2.4 | 目录树已承担分类职能 |
| related-docs | 4 | 1 | 0.6 | 1.5 | 1.6 | 推荐质量难保证 |
| per-doc-pdf | 2 | 1 | 0.6 | 2 | 0.6 | MathJax / mermaid 在 PDF 管线坑多 |
结论
第一批做前三名（generated-json-out-of-git + mathjax-local + ref-integrity-check）：effort 均在一周内，消除的都是每天在付的隐性成本（diff 噪音 / CDN 依赖 / 引用腐烂），且全是构建链路改动，不碰文档内容。第二批候补 new-doc-scaffold 与 backlinks-panel。
开放问题
ref-integrity-check 的 fig-/tbl- 锚点构建期不可见问题— 已解决（2026-06-10）：scripts/check-refs.mjs读 label map 单独校验，接入 build 链。generated-json-out-of-git 的消费方确认— 已确认（2026-06-10）：仅 docs-site 内部读取，无外部消费方，已 untrack。onBrokenLinks仍为'warn''throw'。顺带修复 gen-sidebars 路由推导两个 bug（日期前缀误剥 / 同名目录索引塌缩）。backlinks-panel（第二批候补）— 已落地（2026-06-10）：scripts/gen-backlinks.mjs构建时生成反向链接 map，src/theme/DocItem/Footer渲染"被引用于"面板。- offline-bundle 与 mathjax-local 范围重叠：MathJax 已本地化，其余外网依赖待盘点（字体、其它 CDN script）。