文档站开发

本站 = cikio 的对外文档站，基于 Astro + Starlight，构建为纯静态站点， 由独立的 Cloudflare Worker cikio-docs 托管（Static Assets，无 SSR、无后端逻辑）。

项	值
线上地址	https://docs.cikio.cn
部署单元	Worker cikio-docs（Static Assets，无 main）
技术栈	Astro 7 + Starlight 0.42 + MDX + starlight-links-validator
仓库位置	monorepo docs/
部署方式	CI 自动（.github/workflows/deploy-docs.yml）+ 本地 run deploy

一、内容与代码分离

位置	归属	说明
docs/content/	正文唯一真源	结构 content/<分区>/... → URL /<分区>/...，走 PR 评审
其余部分（astro.config.mjs、src/、scripts/）	站点代码	配置、品牌样式、内容同步脚本
docs/src/content/docs/	构建产物	每次构建全量重建，已 gitignore，不要手改
docs/.content-cache/	可选的外部内容缓存	默认不用，已 gitignore

构建前 scripts/fetch-content.mjs 会把 content/ 全量同步到 Starlight 的内容根。 默认不联网：只有显式设置 DOCS_CONTENT_REPO 才会去浅克隆外部内容仓库并覆盖同名文件 （用于「内容仓公开、仓库私有」或引入外部作者；启用后拉取失败只告警不阻断构建）。

二、新增一篇文档

1. 在 docs/content/ 下建 .md / .mdx（MDX 才需要 JSX，普通页面用 Markdown 即可）。
2. 接进导航：
   • 放在 policy/ 下 → 无需处理，该目录由 Starlight 的 autogenerate 自动进侧栏， 顺序由 frontmatter 的 sidebar.order 决定；
   • 放在其他位置 → 还要在 docs/astro.config.mjs 的 sidebar 加一条， 并在 docs/scripts/fetch-content.mjs 的 PUBLISHED_SLUGS 加同一个 slug。
3. 尚未定稿 → frontmatter 加 draft: true（生产构建不输出、本地 dev 仍可见，页面上有草稿提示），定稿后删掉这一行。

构建会主动拦下两类错误

fetch-content.mjs 用同一份 PUBLISHED_SLUGS 做双向校验：

• 清单里列的页面必须存在（防改名/删除后留下缺口）；
• content/ 下每个非草稿、非隐藏页面都必须在清单里，autogenerate 目录除外（防写了新页面却没接到导航上）。

另外 Starlight 侧栏里的显式 slug 指向不存在的页面时，Starlight 直接构建失败并点名是哪个 slug。 starlight-links-validator 还会扫描全站内部链接与锚点，死链 / 坏锚点一样让构建失败。

三、路由与 URL

Starlight 的路由完全由文件路径决定，不支持 frontmatter 覆盖 slug：

文件	URL
content/index.mdx	/（首页，刻意不进侧栏）
content/policy/index.md	/policy/
content/dev/authserver.md	/dev/authserver/
content/guides/auth.mdx	/guides/auth/

因此搬文件就是换 URL：分区一旦发布，改名要走评审，必要时补 301 规则。 不要让已发布页面链接到草稿页（线上会是死链，链接校验也会报错）。

四、本地开发

pnpm --filter docs dev           # 同步内容 + 启动本地预览
pnpm --filter docs build         # 同步内容 + 静态构建，产物 docs/dist/
pnpm --filter docs typecheck     # astro sync + astro check
pnpm --filter docs run fetch:content
pnpm --filter docs run deploy    # 同步内容 → 构建 → wrangler deploy

几个约定：

• 侧栏分三组（条款与政策 / 产品与服务 / 开发），每组显式 collapsed: false，默认展开； 首页不进侧栏（它是站点封面，不是一篇文档，入口在左上角站点标题）。
• 自定义项只有三处：站点名与 Logo、src/styles/brand.css 里的主色变量、sidebar 结构。 Starlight 的布局、响应式、深浅色切换保持默认。
• 「编辑此页」链接由 src/routeMiddleware.ts 修正：Starlight 默认用 filePath 拼 GitHub 地址， 而 filePath 落在构建期拷贝的生成物目录里，拼出来的路径在仓库中不存在。 不要用 import.meta.url / import.meta.glob 去绕这个问题（中间件会被打进预渲染产物，取值不可靠）。
• 未命中的路径由 wrangler.toml 的 [assets] not_found_handling = "404-page" 回落到 content/404.mdx 生成的 404.html（状态码仍是 404）。改 404 文案就改那个文件。

五、部署

已自动化：docs/**（以及根 pnpm-lock.yaml、该工作流自身）推到 main 后， .github/workflows/deploy-docs.yml 自动构建并部署。它独立于 ci.yml （后者 cancel-in-progress: true，会打断上传中的部署）。

• CI 只需要一个 Secret CLOUDFLARE_API_TOKEN；Account ID 已写在 docs/wrangler.toml 里。

• 手动部署仍可用：pnpm --filter docs run deploy。

• 核对线上版本一律看 Version ID，而不是 commit sha：

  pnpm --filter docs exec wrangler deployments list --name cikio-docs

docs/wrangler.toml 刻意不声明 routes：自定义域 docs.cikio.cn 在 Cloudflare Dashboard 手动绑定， 声明了 routes 反而会在部署时改写既有绑定。

相关：团队文档协作规范、开发问题与踩坑记录。