双语文档网站规范

问题与目标

仓库 canonical Markdown 适合 maintainer，但缺少可搜索、易导航且完整双语的阅读体验。旧 gh-pages 是过时 Docusaurus build，也不是由当前 Fronts 2.0 contract 生成。

目标是在 main 维护 Fumadocs source，静态导出后发布到 https://fronts.js.org/，以中英文覆盖应用 ABI、Host Runtime、MF 边界、隔离、package、运维、兼容性、故障排查、贡献、发布和安全。

内容契约

website/content/content-map.json 是唯一 inventory，每个 slug 必须恰有一个 English 与一个 Chinese page。canonical English technical content 从 repository docs 和 public package README 同步；只有源文件 不是完整英文 web article 时才允许 authored English override。中文逐页人工维护，不机器 fallback 到英文。

website/content/docs 是 ignored/generated output，不能直接编辑。精确 API、package export、engine 与 peer range 仍以 source/manifest 为准。generator 可以把 repo-relative link 改写成本地化 route 或 GitHub main link，但不得形成第二套 API contract。

读者契约

/ 显式提供中英文入口；/en/、/zh/ 是本地化 overview；/en/docs/、/zh/docs/ 是结构完全 平行的导航树并兼容 trailing slash。文章输出 canonical/alternate metadata；英文使用 static Orama， 中文使用 Mandarin tokenizer；Mermaid client-side render；每个 application HTML 带完整 source revision； layout 可跳转到 main 上对应 source。

不根据 cookie 或 browser language 隐式 redirect。显式 locale route 让 GitHub Pages export 可确定， 缓存与共享链接也更稳定。

验收条件

1. 生成 22 对英文/中文页面，并拒绝 docs 任意层级未映射 canonical doc。
2. 每页有 title、description、sourcePath、实质内容和多个 section；中文包含中文且不回链到英文文档树。
3. 全新 next build 导出 root、两个 home、44 个文档 route 和 static search。
4. output check 证明 route/asset 存在、HTML lang 与 revision 正确、双语 search 含 Host guide。
5. Chromium E2E 证明语言入口、两棵 doc tree、深层 runtime article 与中英文搜索。
6. 只有 clean 且等于 origin/main 的 main commit 可以部署。
7. deployment byte-for-byte 保留原 CNAME，只发布 export + .nojekyll，commit 无 parent。
8. branch 更新用 exact force lease，验证 remote SHA，并等 domain 提供嵌入 revision 后才成功。

Rollout、rollback 与风险

首次 rollout 仅在本地验证通过且 main push 成功后替换旧 branch。脚本输出 previous/new SHA；原 CNAME 保持不变，Pages 继续使用当前 custom domain。文档回归应在 main fix/revert 后重新部署。紧急服务故障可 从已知良好 main revision 重建并以 exact lease 发布，不把旧 Docusaurus 当正常 rollback。

破坏性 branch rewrite 与 public domain 更新是高风险外部副作用。评审必须确认 source revision、lease、 CNAME bytes、parent count、tree inventory、domain response 与 Pages 仍从 gh-pages root 发布。内容侧主要 风险是 mapping stale、中文假 fallback、generated link 失效和过度兼容承诺；inventory、localized link、 search、E2E 与 support vocabulary 降低风险，但技术翻译仍需 maintainer review。

验证

pnpm docs:check
pnpm website:check
node --check scripts/deploy-website.mjs
pnpm website:deploy -- --dry-run --skip-check --skip-online-verification

授权部署后，还要确认 remote gh-pages 没有 parent、CNAME 精确一致、线上 /en/docs/ 暴露 main revision， 并人工评审 repository Pages setting、TLS 和首次公开渲染。