feat(docs): add static generation and search indexes

2026-09-20 16:23:32 +08:00
parent a57fdbe7c6
commit 9635de56e8
19 changed files with 529 additions and 169 deletions
@@ -1,35 +1,40 @@
-# React + TypeScript + Vite
+# Documentation site

-This template provides a minimal setup to get React working in Vite with HMR and some Oxlint rules.
+文档站使用 Vite、React、Satteri 和 MDX。默认语言为 `zh-Hans`，英文页面位于 `/en-US`。

-Currently, two official plugins are available:
+## Development

- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
-
-## React Compiler
-
-The React Compiler is enabled on this template. See [this documentation](https://react.dev/learn/react-compiler) for more information.
-
-Note: This will impact Vite dev & build performances.
-You can also try [the experimental native React Compiler support in plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md#rust-react-compiler) by using `compiler: true` in the plugin options instead of using the Babel plugin.
-
-## Expanding the Oxlint configuration
-
-If you are developing a production application, we recommend enabling type-aware lint rules by installing `oxlint-tsgolint` and editing `.oxlintrc.json`:
-
-```json
-{
-  "$schema": "./node_modules/oxlint/configuration_schema.json",
-  "plugins": ["react", "typescript", "oxc"],
-  "options": {
-    "typeAware": true
-  },
-  "rules": {
-    "react/rules-of-hooks": "error",
-    "react/only-export-components": ["warn", { "allowConstantExport": true }]
-  }
-}
+```sh
+bun run --cwd docs dev
 ```

-See the [Oxlint rules documentation](https://oxc.rs/docs/guide/usage/linter/rules) for the full list of rules and categories.
+开发服务器直接监听 `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 恢复交互，后续站内导航仍由轻量客户端路由处理。
+
+## Search data
+
+搜索正文不会打进入口 JavaScript：
+
+- 生产构建从 MDX 原始文本生成 `dist/search/zh-Hans.json` 和 `dist/search/en-US.json`；
+- 用户第一次执行搜索时，浏览器只请求当前语言的索引，并在当前会话中缓存；
+- 切换语言后才会按需请求另一份索引；
+- MDX 页面组件按文章拆分为独立 chunk；
+- 开发模式使用相同的索引生成逻辑，但从 Vite 监听中的 MDX 源文件即时构建。
+
+新增符合 `packages/<package>/docs/<locale>/**` 目录约定的文档后，无需手工维护搜索列表。