用途
本技能用于在编写或审查 Rspress v2 站点时应用一套最佳实践规则，覆盖配置、CLI、文档结构与导航、写作与 frontmatter、MDX 与组件、主题与样式、国际化与搜索、资源与公共文件、插件与集成、构建部署与调试等环节。
主要能力
配置
- 使用 rspress.config.ts 以及来自 @rspress/core 的 defineConfig。
- 当文档不在默认 docs/ 目录下时，显式设置 root。
- 将 title、description、icon、logo、base、lang 等站点级设置保留在配置中，而不是在页面文件中重复。
- 优先使用 Rspress 一等选项，而不是自定义主题代码或底层打包器覆盖。
- 将自定义主题代码放在顶层 theme/ 目录，并从 @rspress/core/theme-original 导入原始主题部分。
CLI
- 使用 rspress dev 进行本地开发。
- 使用 rspress build 生成生产输出。
- 使用 rspress preview 仅用于本地预览已构建站点。
- 仅当 CSS 变量、类覆盖或布局包裹无法解决定制需求时，才使用 rspress eject。
文档结构与导航
- 将文档内容放在一个清晰的 docs 根目录下，按主题或工作流分组页面，而不是按团队归属分组。
- 使用 _meta.json 或 _nav.json 控制侧边栏和导航的标签与顺序，而不是在文件名中编码顺序。
- 将可复用的 MDX 片段或共享组件放在共享文件中，而不是在多个页面中重复。
- 保持落地页简洁，并从落地页链接到更深入的任务导向指南。
写作与 frontmatter
- 添加清晰的 title 和 description frontmatter，仅在页面默认值不足时设置 sidebar、outline、navbar 或 footer。
- 根据布局需求有意识地使用 pageType: home、doc、doc-wide、custom 或 blank。
- 编写任务优先的标题和简短引言；技术文档中避免营销化文案。
- 每页优先一个主题，按工作流或功能领域拆分过长的页面。
- 保持代码示例最小、可运行且版本准确。
MDX 与组件
- 使用 MDX 实现交互式文档和嵌入组件，但保持主要叙述可作为纯 markdown 理解。
- 优先使用有文档的 Rspress 主题/运行时 API，而不是从内部源码路径导入。
- 对于应用级 UI 或 provider，使用 globalUIComponents 或主题覆盖，而不是在每个页面重复导入。
主题与样式
- 品牌色、间距和表面样式优先使用 CSS 变量。
- 在 eject 内置组件之前，优先使用 BEM 类覆盖或 Layout 插槽。
- 在 theme/ 文件中，保留 export * from '@rspress/core/theme-original'，除非有意替换某个具名导出。
- 除非配置、CSS 和包裹无法满足需求，否则避免完整组件 eject。
国际化、搜索与 AI
- 对于多语言站点，按语言目录组织本地化内容，并在可行时保持导航镜像。
- 保持 description 及其他 frontmatter 文本与页面内容语言一致。
- 有意识地配置搜索：中小型站点使用本地搜索，当规模或跨版本索引需要时使用托管搜索。
- 仅当站点受益于机器可读输出时启用 llms 或 ssgMd，并保持 description 准确，因为这些输出会呈现页面摘要。
资源与公共文件
- 当源管理的图片和组件属于内容时，从 docs/theme 源导入。
- 仅将 public/ 用于必须保持稳定 URL 路径的资源，例如 favicon、社交图片或下载文件。
- 通过绝对站点路径引用 public 资源，并确保设置 base 后仍能正常工作。
插件与集成
- 在构建自定义方案之前，优先使用官方 Rspress 插件处理搜索、预览和 API 文档场景。
- 对于组件或库文档，当需要交互式演示或 API 表格时，使用 @rspress/plugin-preview 和 @rspress/plugin-api-docgen。
- 在配置中显式保留插件使用，并移除未使用的插件以降低维护成本。
构建、部署与调试
- 同时验证 rspress dev 和 rspress build；在 dev 中可用的页面在静态生成时仍可能失败。
- 部署前验证断链、缺失资源和错误的 base 处理。
- 除非托管工作流明确要求提交产物，否则将生成输出排除在源码控制之外。
- 调试内容问题时，先检查解析后的 docs 根目录、frontmatter 和主题覆盖，再假设是打包器问题。
文档
- 获取最新 Rspress 文档，请阅读 https://rspress.rs/llms.txt。
- 检查确切选项名称或当前行为时，使用配置和 API 文档。
使用方式
在编写或审查 Rspress v2 站点时应用上述规则。具体安装命令、调用方式等暂未提供。
适用场景
适用于配置、审查或排查 Rspress v2 站点，包括内容约定、导航、MDX、资源、搜索和部署等场景。
限制
资料未提供该技能的具体安装命令、运行环境要求、收费或价格信息、平台支持范围以及效果保证，这些内容暂未提供。