rspress-best-practices

Rspress best practices

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

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

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

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

Writing and 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

MDX and components

• 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