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
```

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

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

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

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

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

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

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

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

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

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