simple-react-app-kit/docs/README.md

Documentation site

文档站使用 Vite、React、Satteri 和 MDX。默认语言为 zh-Hans，英文页面位于 /en-US。

Development

bun run --cwd docs dev

开发服务器直接监听 packages/*/docs/*/**/*.mdx。新增或修改文档后，页面注册表与开发搜索索引会随 Vite 模块图更新。

Static generation

bun run --cwd docs build

构建过程依次执行：

1. 类型检查并构建浏览器资源；
2. 构建仅供预渲染使用的 SSR 入口；
3. 枚举注册表中的首页、设置页和所有双语文章路由；
4. 将每个路由预渲染到 dist/<route>/index.html；
5. 生成 dist/404.html 和按语言拆分的搜索索引；
6. 删除临时 .ssr 目录。

生成的 dist 可以直接部署到静态文件服务。页面在浏览器中使用 hydration 恢复交互，后续站内导航仍由轻量客户端路由处理。

Deployment

文档站通过 Cloudflare Workers Static Assets 部署到 https://react-app-kit.go-slim.dev：

bun run --cwd docs deploy

该命令会先执行完整的静态构建，再通过 Wrangler 发布 dist。首次部署前需要使用 bunx wrangler login 登录拥有 go-slim.dev Cloudflare Zone 的账号；自定义域名、静态路由和 404.html 行为均由 wrangler.jsonc 管理。

Search data

搜索正文不会打进入口 JavaScript：

• 生产构建从 MDX 原始文本生成 dist/search/zh-Hans.json 和 dist/search/en-US.json；
• 用户第一次执行搜索时，浏览器只请求当前语言的索引，并在当前会话中缓存；
• 切换语言后才会按需请求另一份索引；
• MDX 页面组件按文章拆分为独立 chunk；
• 开发模式使用相同的索引生成逻辑，但从 Vite 监听中的 MDX 源文件即时构建。

新增符合 packages/<package>/docs/<locale>/** 目录约定的文档后，无需手工维护搜索列表。