rspress-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Rspress Best Practices

Rspress 最佳实践

Apply these rules when writing or reviewing Rspress (v2) sites.

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

Configuration

配置

Use

rspress.config.ts

and

defineConfig

from

@rspress/core

Set
```
root
```
explicitly when docs are not under the default
```
docs/
```
directory
Keep site-wide settings such as
```
title
```
,
```
description
```
,
```
icon
```
,
```
logo
```
,
```
base
```
, and
```
lang
```
in config instead of repeating them in page files
Prefer first-class Rspress options before custom theme code or low-level bundler overrides
Keep custom theme code in a top-level
```
theme/
```
directory and import original theme pieces from
```
@rspress/core/theme-original
```

使用

rspress.config.ts

以及

@rspress/core

中的

defineConfig

当文档不在默认的
```
docs/
```
目录下时，显式设置
```
root
```
将站点级设置（如
```
title
```
、
```
description
```
、
```
icon
```
、
```
logo
```
、
```
base
```
和
```
lang
```
）放在配置中，不要在页面文件中重复设置
优先使用 Rspress 原生选项，再考虑自定义主题代码或底层打包器覆盖配置
将自定义主题代码放在顶层
```
theme/
```
目录中，并从
```
@rspress/core/theme-original
```
导入原始主题模块

CLI

Use
```
rspress dev
```
for local development
Use
```
rspress build
```
for production output
Use
```
rspress preview
```
only for local preview of the built site
Use
```
rspress eject
```
only when CSS variables, class overrides, or layout wrapping cannot solve the customization

使用
```
rspress dev
```
进行本地开发
使用
```
rspress build
```
生成生产环境输出
仅在本地预览构建后的站点时使用
```
rspress preview
```
只有当 CSS 变量、类覆盖或布局包装无法满足定制需求时，才使用
```
rspress eject
```

Docs Structure And Navigation

文档结构与导航

Keep docs content under one clear docs root and group pages by topic or workflow, not by team ownership
Use
```
_meta.json
```
or
```
_nav.json
```
to control sidebar and navigation labels/order instead of encoding order in filenames
Put reusable MDX snippets or shared components in shared files instead of duplicating them across pages
Keep landing pages concise and link to deeper task-oriented guides from them

将文档内容放在一个清晰的文档根目录下，按主题或工作流分组页面，而非按团队归属分组
使用
```
_meta.json
```
或
```
_nav.json
```
控制侧边栏和导航的标签/顺序，不要在文件名中编码顺序
将可复用的 MDX 代码片段或共享组件放在共享文件中，不要在多个页面中重复编写
保持首页简洁，并从首页链接到更深入的任务导向指南

Writing And Frontmatter

写作与前置元数据（Frontmatter）

Add clear
```
title
```
and
```
description
```
frontmatter, and set
```
sidebar
```
,
```
outline
```
,
```
navbar
```
, or
```
footer
```
only when page defaults are not enough
Use
```
pageType: home
```
,
```
doc
```
,
```
doc-wide
```
,
```
custom
```
, or
```
blank
```
intentionally based on layout needs
Write task-first headings and short intros; avoid marketing-heavy copy in technical docs
Prefer one topic per page and split overly long pages by workflow or feature area
Keep code examples minimal, runnable, and version-accurate

添加清晰的
```
title
```
和
```
description
```
前置元数据，仅当页面默认设置不足时才设置
```
sidebar
```
、
```
outline
```
、
```
navbar
```
或
```
footer
```
根据布局需求，有目的地使用
```
pageType: home
```
、
```
doc
```
、
```
doc-wide
```
、
```
custom
```
或
```
blank
```
编写以任务为导向的标题和简短介绍；避免在技术文档中使用过重的营销性文案
优先每页一个主题，根据工作流或功能区域拆分过长的页面
保持代码示例简洁、可运行且版本准确

MDX And Components

MDX 与组件

Use MDX for interactive docs and embedded components, but keep the main narrative understandable as plain markdown
Prefer documented Rspress theme/runtime APIs over importing from internal source paths
For app-wide UI or providers, use
```
globalUIComponents
```
or theme overrides instead of repeating imports in each page

使用 MDX 制作交互式文档和嵌入组件，但确保主要内容可以作为纯 Markdown 被理解
优先使用已文档化的 Rspress 主题/运行时 API，而非从内部源路径导入
对于全局 UI 或提供者，使用
```
globalUIComponents
```
或主题覆盖，不要在每个页面中重复导入

Theme And Styling

主题与样式

Prefer CSS variables for brand colors, spacing, and surface styling
Prefer BEM class overrides or
```
Layout
```
slots before ejecting built-in components
In
```
theme/
```
files, keep
```
export * from '@rspress/core/theme-original'
```
unless intentionally replacing a named export
Avoid full component ejection unless config, CSS, and wrapping cannot meet the requirement

优先使用 CSS 变量设置品牌颜色、间距和表面样式
在 eject 内置组件之前，优先使用 BEM 类覆盖或
```
Layout
```
插槽
在
```
theme/
```
文件中，除非有意替换命名导出，否则保留
```
export * from '@rspress/core/theme-original'
```
除非配置、CSS 和包装无法满足需求，否则避免完全 eject 组件

I18n, Search, And AI

国际化（I18n）、搜索与 AI

For multilingual sites, organize locale content under per-language directories and keep navigation mirrored where practical
Keep descriptions and other frontmatter text in the same language as the page content
Configure search intentionally: use local search for small or medium sites, and hosted search when scale or cross-version indexing requires it
Enable
```
llms
```
or
```
ssgMd
```
only when the site benefits from machine-readable outputs, and keep descriptions accurate because those outputs surface page summaries

对于多语言站点，将区域内容按语言目录组织，并尽可能保持导航结构一致
保持描述和其他前置元数据文本与页面内容语言一致
有目的地配置搜索：中小型站点使用本地搜索，当需要规模化或跨版本索引时使用托管搜索
仅当站点能从机器可读输出中获益时才启用
```
llms
```
或
```
ssgMd
```
，并确保描述准确，因为这些输出会展示页面摘要

Assets And Public Files

资源与公共文件

Import source-managed images and components from docs/theme source when they belong to the content
Use
```
public/
```
only for assets that must keep stable URL paths, such as favicons, social images, or download files
Reference public assets by absolute site path and make sure they still work when
```
base
```
is set

当图片和组件属于内容时，从 docs/theme 源中导入受源管理的图片和组件
仅将需要保持稳定 URL 路径的资源（如 favicon、社交图片或下载文件）放在
```
public/
```
目录中
使用绝对站点路径引用公共资源，并确保在设置
```
base
```
时仍能正常工作

Plugins And Integration

插件与集成

Prefer official Rspress plugins for search, preview, and API-doc scenarios before building custom solutions
For component or library docs, use
```
@rspress/plugin-preview
```
and
```
@rspress/plugin-api-docgen
```
when interactive demos or API tables are needed
Keep plugin usage explicit in config and remove unused plugins to reduce maintenance cost

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

Build, Deploy, And Debugging

构建、部署与调试

Validate both
```
rspress dev
```
and
```
rspress build
```
; a page that works in dev can still fail during static generation
Verify broken links, missing assets, and wrong
```
base
```
handling before deployment
Keep generated output out of source control unless the hosting workflow explicitly requires committed artifacts
When debugging content issues, inspect the resolved docs root, frontmatter, and theme overrides before assuming a bundler problem

同时验证
```
rspress dev
```
和
```
rspress build
```
；在开发环境中正常工作的页面仍可能在静态生成过程中失败
部署前检查断链、缺失资源和
```
base
```
处理错误
除非托管工作流明确要求提交构建产物，否则不要将生成的输出纳入版本控制
排查内容问题时，先检查解析后的文档根目录、前置元数据和主题覆盖，再假设是打包器问题

Documentation

参考文档

For the latest Rspress docs, read https://rspress.rs/llms.txt
Use the config and API docs when checking exact option names or current behavior

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