rstackjs/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

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