Project docs site

Project docs site 指项目在工程仓库内维护一个独立的 web 文档站点，通常以 docs-site/、docs-pages.yml 或等价 publish workflow、docs:build / build-docs-site、DOCS_PORT 等入口体现。它不是普通 docs/ 目录、README 汇总页、Storybook、产品 UI 或 Astro 博客；本 Topic 只覆盖“文档站本身是可构建、可预览、可发布的交付面”的项目模式。

这个模式的核心是把 README 保持为短入口，把完整部署、使用、配置、运维、排障、API、产品说明或硬件设计说明放到站点里，再让 CI workflow 把它当成独立交付面发布。正式入口可以是 GitHub Pages，也可以是主站 /docs/ 子路径上的 EdgeOne 等静态托管目标；GitHub Pages 甚至可以只保留为热备。用 codebase-design 的语言说，文档站是一条独立 Seam：它对读者暴露的 Interface 是导航、页面结构、版本化构建和公开 URL；站点生成器、内容组织、Storybook 链接和发布 workflow 是内部 Implementation。这条 Seam 保持清晰时，维护者能在不扰动产品 UI 或服务 runtime 的情况下更新外部文档。

当 project snapshot 或 checked-in 配置明确显示仓库有 docs-site/、文档站 package、文档站 build/preview 脚本，且站点由 docs-pages.yml 或等价发布流程作为独立交付物发布时使用。代表样本包括 Dockrev 的 Rspress 文档站、OctoRill 的 public docs-site、Mains Aegis 的设备文档站、KaisouMail 的双语 Rspress 文档站，以及 IsolaRail 这种“主 web app 占根路径，docs site 挂在 /docs/ 子路径”的组合静态发布结构（projects/dockrev.md、projects/isolarail.md、projects/octo-rill.md、projects/mains-aegis.md、projects/kaisoumail.md）。

如果仓库只有 docs/ Markdown、内部 design docs、README、Storybook docs addon，或 Astro public content site，不应自动命中本 Topic。那些分别归到 System design docs、Storybook component QA / Storybook accessibility、Astro site 或普通项目文档维护。若只在 bootstrap 脚本里提到 docs-site/ 依赖安装，但 snapshot 没证明文档站是当前发布面，应先补 project snapshot 再提升到这个 Topic。

• 默认把文档站当作独立交付面，而不是产品 UI 的附属路由。dockrev 把完整部署、使用、运维、排障和 API 文档放在 docs-site/，README 只做快速入口；这适合运维工具，因为用户需要先理解部署和风险，再进入管理 UI（projects/dockrev.md）。
• 技术栈上，当前样本集中在 Rspress + package scripts + GitHub Actions workflow，但“托管平台是谁”不是 Topic 的核心。dockrev 暴露 docs:dev、docs:build、docs:preview，mains-aegis 使用 DOCS_PORT 覆盖默认端口，kaisoumail 用 build-docs-site 放进 Bun workspace gate，isolarail 则把 docs site 作为 /docs/ 子站点装进主站组合 artifact；维护时要把这些脚本和 publish path 一起列入验证，而不是只跑产品 web build（projects/dockrev.md、projects/isolarail.md、projects/mains-aegis.md、projects/kaisoumail.md）。
• 内容风格要跟项目风险匹配。运维工具偏部署/使用/排障/API，GitHub 动态产品要同步 quick start、config、product 和 internal docs，硬件设备项目要把硬件行为、质量门禁和只读控制台边界讲清，Cloudflare 控制面项目则需要中英双语入口和部署环境说明（projects/dockrev.md、projects/octo-rill.md、projects/mains-aegis.md、projects/kaisoumail.md）。
• 文档站发布应有自己的 workflow 或 gate。多个样本都出现 .github/workflows/docs-pages.yml 或等价 docs publish workflow，说明 docs deploy 与 PR/main/release gate 是并列交付链路；改导航、base path、Storybook 链接或站点 build 配置时，要验证 publish workflow 会消费到正确 artifact。对 isolarail 这类仓库，还要额外验证根站点与 /docs/ 子站点是否来自同一份组合静态产物（projects/dockrev.md、projects/isolarail.md、projects/octo-rill.md、projects/kaisoumail.md）。
• Docs Pages 是 expected-success workflow；它最终以 failure 结束时应进入 generic workflow failure sidecar，并保留 docs run 的具体 run_id/run_attempt/URL。通知与 docs publish 仍是两个独立交付面，不能把告警逻辑塞回站点 build job（projects/dockrev.md）。
• Storybook 可以被文档站链接，但不能和文档站混为一谈。kaisoumail 的 docs-site 链接 /storybook.html 与 /zh/storybook.html，这说明 Storybook 是公开资产；坏掉会影响 docs-site，但组件 QA、a11y 和文档站导航仍是不同 Seam（projects/kaisoumail.md）。
• 本地预览端口要可覆盖，并遵守 port lease。dockrev 和 mains-aegis 都记录 docs-site 默认 50885 且可通过 DOCS_PORT 覆盖；后续 Agent 不应直接抢默认端口，也不要把 docs-site preview 冒充产品 web demo（projects/dockrev.md、projects/mains-aegis.md）。
• 不要预设 docs site 一定独占根域名或一定由 GitHub Pages 提供。isolarail 证明 docs site 可以稳定作为主站 /docs/ 子路径发布，而 GitHub Pages 只保留为热备与 DNS rollback source（projects/isolarail.md）。

• projects/dockrev.md：运维工具文档站样本。它用 docs-site/ 承载完整部署、使用、运维、排障和 API 文档，根 README 保持短入口，根 package.json 暴露 docs dev/build/preview 脚本，.github/workflows/docs-pages.yml 负责发布。
• projects/isolarail.md：组合静态发布样本。web/ 主站占根路径 /，docs-site/ 挂到 /docs/，再把同一份静态 artifact 同时发到 EdgeOne 正式入口与 GitHub Pages 热备。
• projects/octo-rill.md：产品化 Rust 服务 + React UI + public docs-site 样本。README 同时指向 public docs-site、quick start、config、product 和 internal docs，适合观察“公开站点与内部设计文档必须同步”的维护习惯。
• projects/mains-aegis.md：设备 mono-repo 文档站样本。docs/ 是工程设计中心，docs-site/ 用 Rspress 生成公开站点，内容风格围绕硬件行为、只读运维 UI、安全边界和质量门禁。
• projects/kaisoumail.md：Cloudflare 控制面和双语文档站样本。docs-site/ 使用 Rspress，包含中文部署环境文档，并把 Storybook 作为公开资产链接进站点，适合参考双语导航与产品 surface 组合。

• 把“有 Markdown 文档”误判为 Project docs site，会把普通 docs/ 和可发布 web 站点混在一起。修正方式是检查 docs-site/package.json、文档站脚本、发布 workflow 和 project snapshot 是否共同存在。
• 只改 README 或 docs/，忘记同步 docs-site 导航与构建，容易让公开文档站落后于项目 current truth。对于 octo-rill 这类产品，docs-site 与 internal docs 漂移会直接影响配置和行为理解（projects/octo-rill.md）。
• 把 docs-site preview 当成产品 demo，会让验收走错 Seam。mains-aegis 明确要求 Web demo 复用正式前端与正式 route，不把 docs-site 或普通 preview 误算成产品演示面（projects/mains-aegis.md）。
• 忽略端口覆盖会在多 worktree / 多 Agent 环境里撞车。看到 DOCS_PORT 或默认 50885 时，应先走端口租约，再启动文档站（projects/dockrev.md、projects/mains-aegis.md）。
• 文档站发布 workflow 被当成低风险 docs-only 改动，可能导致 GitHub Pages 断链、base path 错误或 Storybook 链接失效。kaisoumail 的公开 Storybook 链接说明 docs-site 破坏也会影响组件文档资产（projects/kaisoumail.md）。
• 误以为 docs site 必须独占发布入口，也会让主站 + /docs/ 组合发布场景被错误拆成两个不一致的 artifact。对 isolarail 这类仓库，文档站路径、主站根路径和 hot backup 路径必须一起验证（projects/isolarail.md）。

• projects/dockrev.md
• projects/isolarail.md
• projects/kaisoumail.md
• projects/mains-aegis.md
• projects/octo-rill.md
• skills/style-project-docs-site/SKILL.md