文档维护#

文档使用锁定的 Rspress 1.47.2。统一在仓库根目录运行：

1pnpm install --frozen-lockfile
2pnpm docs:dev
3pnpm docs:build
4pnpm docs:check
5pnpm exec playwright install chromium
6pnpm docs:smoke
7pnpm docs:preview

dev/build/preview 使用同一份 docs/.rspress/config.ts，文档根为 docs、产物为 doc_build、base 为 /fs-router/。访问终端 URL 下的 /fs-router/。

导航和路径兼容#

中文内容保持扁平目录，不迁到 docs/zh，不增加 /zh/ 前缀。lang: zh 保持 HTML 与搜索语言；显式 themeConfig.nav/sidebar 从现有 _meta.json 生成，绕过 Rspress 1 在只有 lang 而无 locales 时跳过自动导航的分支。

新增页时更新所属 _meta.json。navigation.ts 只接受目前使用的 file/dir 条目，未知类型构建报错，避免悄悄遗漏导航。根导航可增加普通链接。

主题扩展修复标题锚点、代码块键盘访问和文字对比度。patches/ 对固定 Rspress 1.47.2 的搜索键盘处理增加焦点/空结果保护；升级主题时须重验该补丁。

所有现有 Markdown 页面路径保留；英文入口新增 /english，不建立不完整的语言切换映射。English 仅维护精简上手与支持边界。

docs:check 检查构建出的每个本地链接、资源、锚点与中文导航；docs:smoke 启动并关闭 dev/preview，通过 Chromium 检查搜索、键盘、移动菜单、图片和基本无障碍。证据写到 .artifacts/browser，可重复生成。CI 也运行这些检查。

部署流程 保持现有 main → Pages 权限边界。

搜索引擎入口#

构建同时生成 /fs-router/sitemap.xml，列出除 404 外的公开文档 URL；docs:check 验证覆盖范围。站内搜索由 Rspress 的本地索引提供。sitemap 与中英文介绍改善发现入口，但不保证搜索引擎收录、排名或 Star 数。GitHub 仓库 topics 与对外采用计划继续按社区阶段审查。