№ · 专题 CH.08.10
主页 · 🏮 专题 · 文档体系说明 · `docs/` vs `docs-site/`

文档体系说明 · `docs/` vs `docs-site/`

📅 2026-08-10 · 📦 4.5 KB · 🏮 专题 · 📝 MD 文档 🆕 14d 🏷️ 剧情🏷️ 规范🏷️ 玩法设计

写给未来想"在文档站找到设计真值"的人:别去 docs-site 找,真值在 docs/。 docs-site 是渲染后的对外镜像,不是源。

1. 一句话关系

docs/  ──(scripts/docs-to-html/build.py)──>  docs-site/
 源                                       构建产物

| 角色 | 路径 | 谁写 | 谁读 | 同步 | | :--- | :--- | :--- | :--- | :--- | | 源 | docs/ | PM / designer / writer(开发者手写) | 开发者 / PM / 设计师 / 长工 | 手工 | | 构建脚本 | scripts/docs-to-html/ | 历史一次性脚本 | 手动跑 build.py | 一次性 | | 产物 | docs-site/ | build.py 跑出来的 | 玩家 / 公众(部署后) | 站点更新时 |

2. docs-site/ 内部长啥样

| 子目录 | 含义 | 跟 docs/ 关系 | | :--- | :--- | :--- | | docs-site/index.html | 站点首页(武林周报 №07) | 渲染自 docs 整合 | | docs-site/categories.html category.html recent.html | 分类/最近页 | 索引页 | | docs-site/column/ | 专栏(武林周报等) | 渲染自 docs/column/ | | docs-site/tags/ | 标签页(22 个) | 关键词反查 | | docs-site/docs/ | 文档镜像(277 文件) | 跟 docs/ 平行,只读 | | docs-site/raw/ | 源快照(74 文件) | build.py 上次读到的源 | | docs-site/design-system/ | 设计系统页 | tokens + components | | docs-site/assets/ | 静态资源 | css/js/images |

3. 边界规则

3.1 谁写谁读

  • docs/ 写,docs-site/ 不写:任何对设计、剧情、规范的更新, 都直接改 docs/ 下的 .md;docs-site/ 由 build.py 重新生成,不要 手动改 docs-site/docs/<X>.html,会被下次构建覆盖。
  • docs-site/raw/ 跟 docs/ 不强一致:raw/ 是上次 build.py 跑 时的源快照。如果 docs/ 在 build.py 之后改过,raw/ 就是过时的。 这是故意的:站点构建是发布动作,不是持续同步。

3.2 谁能进 docs-site/

  • 玩家 / 公众(部署后)
  • 内部协作者想看"渲染后的样式"(比如校对配图/版式)
  • 不该作为设计真值来源来读

3.3 不进 docs-site/ 的内容

docs/handoff/ docs/daily-plans/ docs/plans/ docs/orchestration/ docs/handoff/archive-index/ 全部不公开,只作内部控制面。 build.py 应跳过这些目录(由 .gitignore 风格过滤控制)。

4. 构建流程

4.1 当前构建脚本

scripts/docs-to-html/build.py 59KB,最近跑于 2026-08-06 11:10:50 (看 docs-site/index.html 里的 ?v=20260806111050 时间戳)。

# 跑构建(本仓库约定)
python scripts/docs-to-html/build.py

# 校验(可选)
python scripts/docs-to-html/check.py

4.2 何时跑

  • 设计拍板后:新增 design/active/<X>.md 后,跑一次 build.py 同步到站点。
  • 剧情定稿后:新增 story/主线故事/月XX-XXX.md 后,跑一次。
  • 武林周报出刊:docs/column/武林周报-YYYY-WW.md 写完后,跑一次。
  • 不要每次 commit 都跑——站点构建是发布动作,跟 npm run build 一类。

4.3 失败兜底

如果 build.py 报错:

  1. 不要手动改 docs-site/ 里的 .html。
  2. 修 docs/ 源里的 markdown frontmatter 或路径。
  3. 重跑 build.py。
  4. 如果反复失败,看 scripts/docs-to-html/check.py 的 lint 规则。

5. 谁该用哪个

| 我想... | 用 | 备注 | | :--- | :--- | :--- | | 改设计 | docs/design/active/<X>.md | 然后跑 build.py | | 看当前在途任务 | docs/handoff/index.md | 不在 docs-site | | 找"胜利规则数值" | docs/design/active/... | 站点版本可能滞后 | | 给玩家看武林周报 | docs-site/ 部署 URL | 公开 | | 看本月 release notes | docs/release-notes/ 写,docs-site/ 渲 | 双源 | | 找 6 月底的玩法方案 | docs/design/6.26玩法/ 或 docs/design/completed/ | 历史方案 |

6. 历史注意事项

  • docs/竖版UI重构/ 是早期方案,1 个文件,基本被 docs/uirefactor/ 取代;后续如不复活可以归档。
  • docs-site/docs/ 镜像跟 docs/ 目录同名,目录结构 1:1 平行,看路径能反推源。
  • docs-site/docs/archive/source-fragments/ 是 docs/archive/source-fragments/ 的快照,源那边只有 1 个 ts 草稿。

7. 后续待办

  • [ ] 把 build.py 接进 CI(可选)
  • [ ] 给 docs-site/ 写一份部署说明(部署在 Cloudflare Pages,看 wrangler.jsonc)
  • [ ] 站点搜索框的索引规则,跟 docs-site/tags/ 的 22 个标签同步
  • [ ] 决定 pitch/ 里的 3 个 HTML 要不要进站点(目前 不进,只有 docs 内部看)