2026-09-20 16:23:32 +08:00
|
|
|
|
# Documentation site
|
2026-09-20 15:53:28 +08:00
|
|
|
|
|
2026-09-20 16:23:32 +08:00
|
|
|
|
文档站使用 Vite、React、Satteri 和 MDX。默认语言为 `zh-Hans`，英文页面位于 `/en-US`。
|
2026-09-20 15:53:28 +08:00
|
|
|
|
|
2026-09-20 16:23:32 +08:00
|
|
|
|
## Development
|
2026-09-20 15:53:28 +08:00
|
|
|
|
|
2026-09-20 16:23:32 +08:00
|
|
|
|
```sh
|
|
|
|
|
|
bun run --cwd docs dev
|
|
|
|
|
|
```
|
2026-09-20 15:53:28 +08:00
|
|
|
|
|
2026-09-20 16:23:32 +08:00
|
|
|
|
开发服务器直接监听 `packages/*/docs/*/**/*.mdx`。新增或修改文档后，页面注册表与开发搜索索引会随 Vite 模块图更新。
|
2026-09-20 15:53:28 +08:00
|
|
|
|
|
2026-09-20 16:23:32 +08:00
|
|
|
|
## Static generation
|
2026-09-20 15:53:28 +08:00
|
|
|
|
|
2026-09-20 16:23:32 +08:00
|
|
|
|
```sh
|
|
|
|
|
|
bun run --cwd docs build
|
|
|
|
|
|
```
|
2026-09-20 15:53:28 +08:00
|
|
|
|
|
2026-09-20 16:23:32 +08:00
|
|
|
|
构建过程依次执行：
|
2026-09-20 15:53:28 +08:00
|
|
|
|
|
2026-09-20 16:23:32 +08:00
|
|
|
|
1. 类型检查并构建浏览器资源；
|
|
|
|
|
|
2. 构建仅供预渲染使用的 SSR 入口；
|
|
|
|
|
|
3. 枚举注册表中的首页、设置页和所有双语文章路由；
|
|
|
|
|
|
4. 将每个路由预渲染到 `dist/<route>/index.html`；
|
|
|
|
|
|
5. 生成 `dist/404.html` 和按语言拆分的搜索索引；
|
|
|
|
|
|
6. 删除临时 `.ssr` 目录。
|
2026-09-20 15:53:28 +08:00
|
|
|
|
|
2026-09-20 16:23:32 +08:00
|
|
|
|
生成的 `dist` 可以直接部署到静态文件服务。页面在浏览器中使用 hydration 恢复交互，后续站内导航仍由轻量客户端路由处理。
|
|
|
|
|
|
|
|
|
|
|
|
## Search data
|
|
|
|
|
|
|
|
|
|
|
|
搜索正文不会打进入口 JavaScript：
|
|
|
|
|
|
|
|
|
|
|
|
- 生产构建从 MDX 原始文本生成 `dist/search/zh-Hans.json` 和 `dist/search/en-US.json`；
|
|
|
|
|
|
- 用户第一次执行搜索时，浏览器只请求当前语言的索引，并在当前会话中缓存；
|
|
|
|
|
|
- 切换语言后才会按需请求另一份索引；
|
|
|
|
|
|
- MDX 页面组件按文章拆分为独立 chunk；
|
|
|
|
|
|
- 开发模式使用相同的索引生成逻辑，但从 Vite 监听中的 MDX 源文件即时构建。
|
2026-09-20 15:53:28 +08:00
|
|
|
|
|
2026-09-20 16:23:32 +08:00
|
|
|
|
新增符合 `packages/<package>/docs/<locale>/**` 目录约定的文档后，无需手工维护搜索列表。
|
