docs/README.md

# Documentation site

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

## Development

```sh
bun run --cwd docs dev
```

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

## Static generation

```sh
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>：

```sh
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>/**` 目录约定的文档后，无需手工维护搜索列表。
-											feat(docs): add static generation and search indexes
										
										
											2026-09-20 16:23:32 +08:00
+								# Documentation site
-											feat(docs): add bilingual package documentation site
										
										
											2026-09-20 15:53:28 +08:00
-											feat(docs): add static generation and search indexes
										
										
											2026-09-20 16:23:32 +08:00
+								文档站使用 Vite、React、Satteri 和 MDX。默认语言为 `zh-Hans`，英文页面位于 `/en-US`。
-											feat(docs): add bilingual package documentation site
										
										
											2026-09-20 15:53:28 +08:00
-											feat(docs): add static generation and search indexes
										
										
											2026-09-20 16:23:32 +08:00
+								## Development
-											feat(docs): add bilingual package documentation site
										
										
											2026-09-20 15:53:28 +08:00
-											feat(docs): add static generation and search indexes
										
										
											2026-09-20 16:23:32 +08:00
+								```sh
 								bun run --cwd docs dev
 								```
-											feat(docs): add bilingual package documentation site
										
										
											2026-09-20 15:53:28 +08:00
-											feat(docs): add static generation and search indexes
										
										
											2026-09-20 16:23:32 +08:00
+								开发服务器直接监听 `packages/*/docs/*/**/*.mdx`。新增或修改文档后，页面注册表与开发搜索索引会随 Vite 模块图更新。
-											feat(docs): add bilingual package documentation site
										
										
											2026-09-20 15:53:28 +08:00
-											feat(docs): add static generation and search indexes
										
										
											2026-09-20 16:23:32 +08:00
+								## Static generation
-											feat(docs): add bilingual package documentation site
										
										
											2026-09-20 15:53:28 +08:00
-											feat(docs): add static generation and search indexes
										
										
											2026-09-20 16:23:32 +08:00
+								```sh
 								bun run --cwd docs build
 								```
-											feat(docs): add bilingual package documentation site
										
										
											2026-09-20 15:53:28 +08:00
-											feat(docs): add static generation and search indexes
										
										
											2026-09-20 16:23:32 +08:00
+								构建过程依次执行：
-											feat(docs): add bilingual package documentation site
										
										
											2026-09-20 15:53:28 +08:00
-											feat(docs): add static generation and search indexes
										
										
											2026-09-20 16:23:32 +08:00
+. 类型检查并构建浏览器资源；
 . 构建仅供预渲染使用的 SSR 入口；
 . 枚举注册表中的首页、设置页和所有双语文章路由；
 . 将每个路由预渲染到 `dist/<route>/index.html`；
 . 生成 `dist/404.html` 和按语言拆分的搜索索引；
 . 删除临时 `.ssr` 目录。
-											feat(docs): add bilingual package documentation site
										
										
											2026-09-20 15:53:28 +08:00
-											feat(docs): add static generation and search indexes
										
										
											2026-09-20 16:23:32 +08:00
+								生成的 `dist` 可以直接部署到静态文件服务。页面在浏览器中使用 hydration 恢复交互，后续站内导航仍由轻量客户端路由处理。
-											chore(docs): add Cloudflare deployment
										
										
											2026-09-20 16:29:08 +08:00
+								## Deployment
 								文档站通过 Cloudflare Workers Static Assets 部署到 <https://react-app-kit.go-slim.dev>：
 								```sh
 								bun run --cwd docs deploy
 								```
 								该命令会先执行完整的静态构建，再通过 Wrangler 发布 `dist`。首次部署前需要使用 `bunx wrangler login` 登录拥有 `go-slim.dev` Cloudflare Zone 的账号；自定义域名、静态路由和 `404.html` 行为均由 `wrangler.jsonc` 管理。
-											feat(docs): add static generation and search indexes
										
										
											2026-09-20 16:23:32 +08:00
+								## Search data
 								搜索正文不会打进入口 JavaScript：
 								- 生产构建从 MDX 原始文本生成 `dist/search/zh-Hans.json` 和 `dist/search/en-US.json`；
 								- 用户第一次执行搜索时，浏览器只请求当前语言的索引，并在当前会话中缓存；
 								- 切换语言后才会按需请求另一份索引；
 								- MDX 页面组件按文章拆分为独立 chunk；
 								- 开发模式使用相同的索引生成逻辑，但从 Vite 监听中的 MDX 源文件即时构建。
-											feat(docs): add bilingual package documentation site
										
										
											2026-09-20 15:53:28 +08:00
-											chore(docs): add Cloudflare deployment
										
										
											2026-09-20 16:29:08 +08:00
+								新增符合 `packages/<package>/docs/<locale>/**` 目录约定的文档后，无需手工维护搜索列表。