把 OpenClaw.NET 的 83 篇 Markdown 变成一个网站：完整复盘 - 张善友
内容提要
作者将 OpenClaw.NET 仓库的 83 篇中文文档构建为可搜索、带暗色主题的网站。核心难点是链接处理：校验脚本发现 121 个死链，包括相对路径错误、锚点编码误判和指向源码文件的站外链接。作者自写轻量构建脚本，解析 SITE_MAP.md 生成侧边栏，并将 252 处站外引用渲染为虚线下划线文字，悬停显示原始路径，不伪装成可点击链接。发布前自查密钥，发布后因源文档更新需重建校验，最终实现零死链。
延伸解读
链接处理：文档站构建的隐藏成本
作者发现，将83篇Markdown转为网站时，80%的工作量在链接处理而非渲染。校验脚本报出121个死链，包括相对路径错误、锚点编码误判和指向源码文件的站外链接。这提醒我们，文档站构建中链接的完整性和正确性至关重要，需要专门的校验机制，不能仅依赖渲染工具。
站外链接的诚实处理：不假装可点击
对于指向源码文件的252处站外引用，作者没有删除或留404，而是渲染为虚线下划线文字，悬停显示原始路径。这种“不假装”的做法既保留了信息，又避免了误导用户。在文档工程中，诚实标注链接的可用性是一种被低估的品质，能提升用户体验和信任度。
文档更新与网站同步的挑战
站点发布后，源文档立即更新，新增一篇且修改两篇，导致网站内容滞后。作者通过重建、校验、发布流程，实现了零死链和产物与源一一对应。这揭示了文档站维护的持续性：上线不是终点，而是开始。团队需建立机制，确保网站能及时反映文档变化。
构建流程中的安全自查
发布前，作者用自写扫描器检查私钥、令牌和api_key赋值，确认无泄露后才部署。公开部署是不可撤销的外部动作，安全自查是必要步骤。这提醒开发者，在自动化流程中嵌入安全检查，能避免敏感信息意外暴露，保障项目安全。
Q&A
把 OpenClaw.NET 的 83 篇 Markdown 文档变成网站，主要难点是什么？
主要难点是链接处理。作者用校验脚本发现 121 个死链，包括相对路径错误、锚点编码误判和指向源码文件的站外链接。
为什么作者没有使用 Docusaurus 或 VitePress 等现成框架？
因为仓库根目录没有 mkdocs.yml、docusaurus.config.js 或 package.json，作者不想为 83 篇文档安装重型框架，所以选择自己写轻量构建脚本。
作者如何处理文档中指向源码文件的站外链接？
作者没有删除或留 404，而是将 252 处站外引用渲染为虚线下划线文字，悬停显示原始路径，不伪装成可点击链接。
校验脚本发现了哪些类型的 bug？
发现 5 类 bug：嵌套页文档首页链接写死 index.html、锚点比对未 URL 解码、指向源码文件的链接未处理、右栏目录和侧边栏高亮用 .html 查 .md 索引、正文 H1 与模板标题重复渲染。
发布前作者做了哪些安全检查？
作者自己扫描了私钥模式、令牌模式和 api_key= 赋值，确认没有命中后才发布。
站点发布后源文档更新了，作者如何应对？
作者重新构建、校验，确保 0 死链、0 缺资源，产物与源一一对应（83/83），然后覆盖发布。新文档在 SITE_MAP.md 中未收录，作者在构建脚本补充表中添加正式归类。
