rspress-best-practices

Name: rspress-best-practices
Author: rstackjs

84stars1forks

How to install rspress-best-practices?

rstackjs/agent-skills/rspress-best-practices

$npx -y skills add rstackjs/agent-skills --skill rspress-best-practices

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# Rspress Best Practices
2
3	Apply these rules when writing or reviewing Rspress (v2) sites.
4
5	## Configuration
6
7	- Use `rspress.config.ts` and `defineConfig` from `@rspress/core`
8	- Set `root` explicitly when docs are not under the default `docs/` directory
9	- Keep site-wide settings such as `title`, `description`, `icon`, `logo`, `base`, and `lang` in config instead of repeating them in page files
10	- Prefer first-class Rspress options before custom theme code or low-level bundler overrides
11	- Keep custom theme code in a top-level `theme/` directory and import original theme pieces from `@rspress/core/theme-original`
12
13	## CLI
14
15	- Use `rspress dev` for local development
16	- Use `rspress build` for production output
17	- Use `rspress preview` only for local preview of the built site
18	- Use `rspress eject` only when CSS variables, class overrides, or layout wrapping cannot solve the customization
19
20	## Docs Structure And Navigation
21
22	- Keep docs content under one clear docs root and group pages by topic or workflow, not by team ownership
23	- Use `_meta.json` or `_nav.json` to control sidebar and navigation labels/order instead of encoding order in filenames
24	- Put reusable MDX snippets or shared components in shared files instead of duplicating them across pages
25	- Keep landing pages concise and link to deeper task-oriented guides from them
26
27	## Writing And Frontmatter
28
29	- Add clear `title` and `description` frontmatter, and set `sidebar`, `outline`, `navbar`, or `footer` only when page defaults are not enough
30	- Use `pageType: home`, `doc`, `doc-wide`, `custom`, or `blank` intentionally based on layout needs
31	- Write task-first headings and short intros; avoid marketing-heavy copy in technical docs
32	- Prefer one topic per page and split overly long pages by workflow or feature area
33	- Keep code examples minimal, runnable, and version-accurate
34
35	## MDX And Components
36
37	- Use MDX for interactive docs and embedded components, but keep the main narrative understandable as plain markdown
38	- Prefer documented Rspress theme/runtime APIs over importing from internal source paths
39	- For app-wide UI or providers, use `globalUIComponents` or theme overrides instead of repeating imports in each page
40
41	## Theme And Styling
42
43	- Prefer CSS variables for brand colors, spacing, and surface styling
44	- Prefer BEM class overrides or `Layout` slots before ejecting built-in components
45	- In `theme/` files, keep `export * from '@rspress/core/theme-original'` unless intentionally replacing a named export
46	- Avoid full component ejection unless config, CSS, and wrapping cannot meet the requirement
47
48	## I18n, Search, And AI
49
50	- For multilingual sites, organize locale content under per-language directories and keep navigation mirrored where practical
51	- Keep descriptions and other frontmatter text in the same language as the page content
52	- Configure search intentionally: use local search for small or medium sites, and hosted search when scale or cross-version indexing requires it
53	- Enable `llms` or `ssgMd` only when the site benefits from machine-readable outputs, and keep descriptions accurate because those outputs surface page summaries
54
55	## Assets And Public Files
56
57	- Import source-managed images and components from docs/theme source when they belong to the content
58	- Use `public/` only for assets that must keep stable URL paths, such as favicons, social images, or download files
59	- Reference public assets by absolute site path and make sure they still work when `base` is set
60
61	## Plugins And Integration
62
63	- Prefer official Rspress plugins for search, preview, and API-doc scenarios before building custom solutions
64	- For component or library docs, use `@rspress/plugin-preview` and `@rspress/plugin-api-docgen` when interactive demos or API tables are needed
65	- Keep plugin usage explicit in config and remove unused plugins to reduce maintenance cost
66
67	## Build, Deploy, And Debugging
68
69	- Validate both `rspress dev` and `rspress build`; a page that works in dev can still fail during static generation
70	- Verify broken links, missing assets, and wrong `base` handling before deployment
71	- Keep generated output out of source control unless the hosting workflow explicitly requires committed artifacts
72	- When debugging content issues, inspect the resolved docs root, frontmatter, and theme overrides before assuming a bundler problem
73
74	## Documentation
75
76	- For the latest Rspress docs, read https://rspress.rs/llms.txt
77	- Use the config and API docs when checking exact option names or current behavior

People who liked this also viewed

6 picks

Type

rspress-best-practices

84stars1forks

View on GitHub

How to install rspress-best-practices?

rstackjs/agent-skills/rspress-best-practices

$npx -y skills add rstackjs/agent-skills --skill rspress-best-practices

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Rspress Best Practices
2
3	Apply these rules when writing or reviewing Rspress (v2) sites.
4
5	## Configuration
6
7	- Use `rspress.config.ts` and `defineConfig` from `@rspress/core`
8	- Set `root` explicitly when docs are not under the default `docs/` directory
9	- Keep site-wide settings such as `title`, `description`, `icon`, `logo`, `base`, and `lang` in config instead of repeating them in page files
10	- Prefer first-class Rspress options before custom theme code or low-level bundler overrides
11	- Keep custom theme code in a top-level `theme/` directory and import original theme pieces from `@rspress/core/theme-original`
12
13	## CLI
14
15	- Use `rspress dev` for local development
16	- Use `rspress build` for production output
17	- Use `rspress preview` only for local preview of the built site
18	- Use `rspress eject` only when CSS variables, class overrides, or layout wrapping cannot solve the customization
19
20	## Docs Structure And Navigation
21
22	- Keep docs content under one clear docs root and group pages by topic or workflow, not by team ownership
23	- Use `_meta.json` or `_nav.json` to control sidebar and navigation labels/order instead of encoding order in filenames
24	- Put reusable MDX snippets or shared components in shared files instead of duplicating them across pages
25	- Keep landing pages concise and link to deeper task-oriented guides from them
26
27	## Writing And Frontmatter
28
29	- Add clear `title` and `description` frontmatter, and set `sidebar`, `outline`, `navbar`, or `footer` only when page defaults are not enough
30	- Use `pageType: home`, `doc`, `doc-wide`, `custom`, or `blank` intentionally based on layout needs
31	- Write task-first headings and short intros; avoid marketing-heavy copy in technical docs
32	- Prefer one topic per page and split overly long pages by workflow or feature area
33	- Keep code examples minimal, runnable, and version-accurate
34
35	## MDX And Components
36
37	- Use MDX for interactive docs and embedded components, but keep the main narrative understandable as plain markdown
38	- Prefer documented Rspress theme/runtime APIs over importing from internal source paths
39	- For app-wide UI or providers, use `globalUIComponents` or theme overrides instead of repeating imports in each page
40
41	## Theme And Styling
42
43	- Prefer CSS variables for brand colors, spacing, and surface styling
44	- Prefer BEM class overrides or `Layout` slots before ejecting built-in components
45	- In `theme/` files, keep `export * from '@rspress/core/theme-original'` unless intentionally replacing a named export
46	- Avoid full component ejection unless config, CSS, and wrapping cannot meet the requirement
47
48	## I18n, Search, And AI
49
50	- For multilingual sites, organize locale content under per-language directories and keep navigation mirrored where practical
51	- Keep descriptions and other frontmatter text in the same language as the page content
52	- Configure search intentionally: use local search for small or medium sites, and hosted search when scale or cross-version indexing requires it
53	- Enable `llms` or `ssgMd` only when the site benefits from machine-readable outputs, and keep descriptions accurate because those outputs surface page summaries
54
55	## Assets And Public Files
56
57	- Import source-managed images and components from docs/theme source when they belong to the content
58	- Use `public/` only for assets that must keep stable URL paths, such as favicons, social images, or download files
59	- Reference public assets by absolute site path and make sure they still work when `base` is set
60
61	## Plugins And Integration
62
63	- Prefer official Rspress plugins for search, preview, and API-doc scenarios before building custom solutions
64	- For component or library docs, use `@rspress/plugin-preview` and `@rspress/plugin-api-docgen` when interactive demos or API tables are needed
65	- Keep plugin usage explicit in config and remove unused plugins to reduce maintenance cost
66
67	## Build, Deploy, And Debugging
68
69	- Validate both `rspress dev` and `rspress build`; a page that works in dev can still fail during static generation
70	- Verify broken links, missing assets, and wrong `base` handling before deployment
71	- Keep generated output out of source control unless the hosting workflow explicitly requires committed artifacts
72	- When debugging content issues, inspect the resolved docs root, frontmatter, and theme overrides before assuming a bundler problem
73
74	## Documentation
75
76	- For the latest Rspress docs, read https://rspress.rs/llms.txt
77	- Use the config and API docs when checking exact option names or current behavior

People who liked this also viewed

6 picks

Type