# Rspress Best Practices

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

- Skill: `dahlia/rspress-best-practices` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dahlia/rspress-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dahlia/rspress-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: dahlia (https://skillmd.com/u/dahlia)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dahlia/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