# 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. - **Type:** Skill - **Install:** `agentstack add skill-rstackjs-agent-skills-rspress-best-practices` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [rstackjs](https://agentstack.voostack.com/s/rstackjs) - **Installs:** 0 - **Category:** [Search](https://agentstack.voostack.com/c/search) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [rstackjs](https://github.com/rstackjs) - **Source:** https://github.com/rstackjs/agent-skills/tree/main/skills/rspress-best-practices ## Install ```sh agentstack add skill-rstackjs-agent-skills-rspress-best-practices ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [rstackjs](https://github.com/rstackjs) - **Source:** [rstackjs/agent-skills](https://github.com/rstackjs/agent-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-rstackjs-agent-skills-rspress-best-practices - Seller: https://agentstack.voostack.com/s/rstackjs - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.