| name | rspress-best-practices |
| description | Rspress best practices for config, CLI workflow, content organization, frontmatter, MDX, themes, i18n, search, static assets, deployment, and debugging. Use when writing, reviewing, or troubleshooting Rspress documentation sites. |
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
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
I18n, Search, And 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
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
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
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
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