03 · 把技术文档当作代码维护：从 Markdown 到离线知识站

定位：实现复盘。 本文依据仓库中的两个 Python 构建器、门户页面和浏览器渲染代码。没有重新生成既有站点或电子书，也不把已有 PDF 当作本次完成的排版验证。

知识库的第一个版本通常只有几篇 Markdown。真正的维护压力出现在第二阶段：内容越来越多，目录、跨章节链接、网页版、打印版开始各自变化。一处更新如果需要人工复制三遍，知识库很快就会出现多个互相矛盾的“最新版”。

claude-demo 的做法值得借鉴：保留 Markdown 作为内容源，让脚本处理导航和展示。但它也展示了一个容易忽略的事实——内容可复用，不等于发布协议天然一致。

一、先分清内容、编排和呈现

build_html.py 中的 TOPICS 不是文章正文，而是一个显式编排表。每个主题包含稳定标识、标题、图标、颜色，以及若干“章节标识—章节标题—源文件”元组。整理时，这张表注册了 23 个主题、92 个章节。

三层职责因此很清楚：

层次	当前实现	变更原因
内容层	README.md 与 docs/ 中的 Markdown	修订技术事实、案例和解释
编排层	TOPICS 与路径到章节的映射	新增专题、调整阅读顺序
呈现层	HTML 模板、浏览器路由、侧栏与目录	改善阅读体验

显式列表的优点是可以精确控制阅读路径，缺点是新增文件不会自动进入站点。仓库原有 docs/ 共 164 篇 Markdown，其中不少设计和实验资料并未注册为章节。因此，“目录下有文件”和“网页上能找到文件”是两个不同的检查项。

本次分享系列也只新增 Markdown 和入口，没有偷偷把新文章写入旧构建器并重建整个站点。

二、跨章节链接其实是一种协议

Markdown 中自然的写法是指向另一个文件；离线阅读器希望使用哈希路由。PATH_TO_LOC 与 rewrite_links() 负责在两者之间转换：

源文件相对路径 → 解析为绝对文件路径 → 查主题/章节映射 → 生成阅读器路由

当前转换器会跳过网页 URL、邮件链接和纯锚点。它使用正则处理常见 Markdown 链接，并不是完整的 Markdown AST 解析器。带空格、复杂括号或特殊标题的链接，不能仅凭常见样例成功就认定全部兼容。

更有价值的是一次具体的协议检查。带段落锚点的链接被重写为：

#claude-code/ch03#31-claudemd-项目记忆

但前端 parseHash() 按斜杠解析“主题/章节/段落”，章节标识于是变成了 ch03#31-claudemd-项目记忆。本次单独提取原有函数进行离线检查，实际解析结果是回退到 Claude Code 主题内 ID 为 home 的首章，段落为空；这不是返回全站首页。

这不是“Markdown 不支持中文”的问题，而是链接生成端和路由消费端使用了不同的协议。本次仅记录这一既有问题，没有顺手修改业务实现。迁移到其他知识系统时，至少要分别测试普通章节、带锚点章节、外链和不存在的目标。

三、离线可读，不等于只有一个文件

构建器把 Markdown 内容序列化后嵌入 HTML，浏览器不必再请求原始 .md。但是渲染仍依赖 lib/ 中的 Markdown、Mermaid、代码高亮和样式资源。因此，准确的交付单位是“HTML 加本地依赖目录”，而不是把一个 HTML 文件拷走就万事大吉。

前端按需完成以下步骤：

1. 解析哈希，选择主题和章节。
2. 把 Markdown 转成 HTML。
3. 将 Mermaid 代码块转成图表容器，再触发渲染。
4. 重建侧栏、章节导航和页内目录。

这种轻量结构适合个人或团队的离线资料集，不需要服务端数据库。不过它把内容当作受信任输入：当前使用 innerHTML，Mermaid 配置也较宽松。把 JSON 中的 </ 转义可以避免提前结束脚本标签，但这不等于对任意 Markdown 或 HTML 做了安全清洗。如果未来开放用户投稿或公网编辑，需要另行建立输入可信边界。

图 03：内容、编排和呈现分别承担责任。离线入口仍依赖相邻 lib/；章节锚点协议错配会回到当前主题的 home 章，不是全站首页。

四、同一内容，打印版需要另一套编排

build_ebook.py 选择的是 ai-career-survival 下的两篇文章，而不是整站。它使用 Python Markdown 库，把内容放入面向 A4 的模板，并在每篇转换前调用 reset()，避免解析器状态跨文档残留。

它还移除两篇源文件之间的相对链接、保留链接文字。这种做法对一份连续阅读的电子书是合理的，却不适合网站：网站需要可点击的章节导航，打印物需要连续内容、页次和排版。

这里的脚本输出是 HTML。“可打印为 PDF”不等于代码已经完成了 PDF 渲染、分页检查、字体嵌入和交付质量验证。内容构建、打印渲染和视觉校样应该分别记录。

五、展示实验也有可复用的工程点

background/ 的动态背景不是模型推理效果，而是原生 Canvas 动画。代码处理了设备像素比、窗口尺寸变化、主题切换和全屏事件。它说明一些看起来“很 AI”的展示效果，用确定性的浏览器图形程序就能实现。

这与文档站采用本地依赖的思路一致：选择能满足问题的最小技术，而不是为了“AI 项目”给所有环节都接上模型。

六、怎样安全复核这条构建链

先在独立副本中检查，而不是直接覆盖正在使用的生成文件：

python3 build_html.py
python3 build_ebook.py

第一条会写入既有知识站；第二条需要 Python markdown 包，并写入电子书 HTML。当前构建器有顶层执行语句，单纯 import build_html 也可能触发重建，因此不应把导入当成只读检查。

构建后至少核对：已注册源文件是否存在、本地依赖是否齐全、章节与段落链接是否正确、Mermaid 是否渲染、打印分页是否可接受。若未来继续演进，建议将“读源文件”“构建数据”“写产物”拆开，使链接和编排逻辑可以无副作用测试；这是一项建议，不是仓库现有能力。

结语

文档工程的核心不是把 Markdown 变漂亮，而是让内容来源、导航协议、输出格式和验证责任彼此独立。真正值得复用的，是一份知识只维护一次，以及每种发布形式都有自己的验收方法。