rspress-best-practices

Rspress 最佳实践

编写或审查 Rspress（v2）站点时，请遵循以下规则。

配置

• 使用 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

文档结构和导航

• 将文档内容集中在一个清晰的文档根目录下，并按主题或工作流组织页面，而不是按团队归属组织
• 使用 _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 变量设置品牌颜色、间距和表面样式
• 优先使用 BEM 类覆盖或 Layout 插槽，再考虑弹出内置组件
• 在 theme/ 文件中，除非有意替换某个具名导出，否则保留 export * from '@rspress/core/theme-original'
• 除非配置、CSS 和布局包装无法满足需求，否则避免完全弹出组件

国际化、搜索和 AI

• 对于多语言站点，将各语言内容放在对应的语言目录下，并尽可能保持导航结构一致
• 保持描述和其他 frontmatter 文本与页面内容使用相同语言
• 有目的地配置搜索：小型或中型站点使用本地搜索；当规模或跨版本索引有需求时，使用托管搜索
• 仅当站点能从机器可读输出中受益时，才启用 llms 或 ssgMd；并确保描述准确，因为这些输出会展示页面摘要

资源文件和公共文件

• 对于属于内容的图片和组件，从文档或主题源码中导入由源码管理的资源
• 仅当资源必须保持稳定的 URL 路径时才使用 public/，例如 favicon、社交图片或下载文件
• 使用站点绝对路径引用公共资源，并确保设置 base 后仍能正常使用

插件和集成

• 在构建自定义方案之前，优先使用官方 Rspress 插件来处理搜索、预览和 API 文档场景
• 对于组件或库文档，当需要交互式演示或 API 表格时，使用 @rspress/plugin-preview 和 @rspress/plugin-api-docgen
• 在配置中明确使用的插件，并移除未使用的插件，以降低维护成本

构建、部署和调试

• 验证 rspress dev 和 rspress build；在开发模式下正常的页面，在静态生成期间仍可能失败
• 部署前检查失效链接、缺失资源以及 base 处理是否有误
• 除非托管工作流明确要求提交生成的产物，否则不要将其纳入源代码管理
• 调试内容问题时，先检查解析后的文档根目录、frontmatter 和主题覆盖项，再判断是否为打包器问题

文档

• 如需查阅最新的 Rspress 文档，请访问 https://rspress.rs/llms.txt
• 检查确切的选项名称或当前行为时，请查阅配置和 API 文档