rspress-core

name

rspress-core

description

Author and configure a general RSPress 2.x documentation site — the framework surface a docs site needs regardless of any plugin. Use when editing _meta.json (sidebar) or _nav.json (navbar); setting page frontmatter (pageType, hero/features, sidebar/outline toggles); using built-in MDX components (Badge, Tabs, PackageManagerTabs, Steps, containers, code-block line highlighting); theming with --rp-* CSS variables or the globalStyles hook; configuring RSPress locales (i18n) or multiVersion; or importing from @rspress/core/theme. Do NOT use for rspress-plugin-api-extractor's own options, --api-* variables, or API-model plumbing (see plugin-config); for the editorial craft of what prose to write (see doc-writer); or for what goes inside a with-api code fence (see twoslash).

rspress-core

Load this skill for the general RSPress 2.x surface — the framework mechanics a documentation site needs no matter which plugins it runs: routing, the sidebar and navbar files, page frontmatter, built-in components, --rp-* theming, and i18n/multiVersion. It is package-agnostic: nothing here is specific to rspress-plugin-api-extractor.

Three sibling skills route into this one for generic RSPress questions, so keep the boundary sharp:

• rspress-plugin-api-extractor's own configuration — its options, --api-* variables, .api.json model plumbing — see plugin-config.
• The editorial craft of what to write and how to structure prose — see doc-writer.
• What goes inside a with-api code fence — notation, @errors, ---cut--- — see twoslash.

Boundary: looks similar, is not

This skill and plugin-config both configure "the site," so their surfaces read as one. They are not.

• rspress-core owns the generic RSPress surface: _meta.json/_nav.json, page frontmatter, built-in components, and the --rp-* CSS variables that theme RSPress's chrome (sidebar, nav, hero, page background).
• plugin-config owns the plugin: ApiExtractorPlugin options, the generated api/ tree, and the --api-* variables that theme the generated components.

--rp-* and --api-* are two different variable families. Restyling the sidebar or the home hero is --rp-* (this skill); restyling a generated signature block is --api-* (plugin-config).

Mental model

RSPress is convention-routed. The docs/ tree (the root in rspress.config.ts) maps 1:1 to routes: docs/guide/intro.md serves at /guide/intro. You shape two things on top of that file-to-route mapping:

• The sidebar — a _meta.json in a directory orders and labels that directory's pages. Contextual, per-section.
• The navbar — a single _nav.json at the docs root defines the global top navigation.

Everything else — a page's title, layout, whether it is a home page — is set in that page's frontmatter. Site-wide settings (title, theme, locales, plugins) live in rspress.config.ts.

The two version traps

RSPress 1.x content is all over the internet and in older skills. Two 1.x patterns silently break on 2.x — encode them loudly:

1. Import components from @rspress/core/theme, never rspress/theme. The bare rspress/theme specifier is the 1.x package; on RSPress 2.x it does not resolve (or resolves to nothing), so a component import from it fails the build or renders nothing. Every built-in component — Badge, Tabs, Steps, PackageManagerTabs — comes from @rspress/core/theme.

2. _meta.json is an ARRAY, never an object. RSPress 2.x sidebar metadata is a JSON array of entry objects ([ { "type": "dir", ... }, ... ]). The 1.x object form ({ "intro": "Introduction", ... }) is not read on 2.x — a page using it gets an auto-generated sidebar instead, silently ignoring your ordering and labels.

Trap: both failures are quiet. A rspress/theme import or an object-form _meta.json does not error with a helpful message — the component vanishes or the sidebar falls back to alphabetical. If a sidebar or component "isn't taking," check these two first.

Config file anatomy

rspress.config.ts is a defineConfig({...}) from @rspress/core. The fields a docs author touches most:

• root — the docs directory (usually "docs"), the base of the file-to-route map.
• title / description / icon / logo — site identity.
• themeConfig — navbar social links, footer, the outline, llmsUI, and other theme-level settings.
• globalStyles — a path to a CSS file injected site-wide; this is where --rp-* overrides live (see references/theming.md).
• locales / lang — internationalization (see references/i18n-multiversion.md).
• multiVersion — versioned docs (same reference).
• plugins — where ApiExtractorPlugin(...) and other plugins are registered (the plugin's own options are plugin-config's).
• route — routing options such as cleanUrls.

Common mistakes

• Importing from rspress/theme. That is 1.x; on 2.x use @rspress/core/theme. The component silently fails to render.
• Writing _meta.json as an object. 2.x reads the array form only; the object form is ignored and the sidebar falls back to alphabetical order.
• Reaching for --api-* to theme the sidebar or hero. Those are the plugin's generated-component variables; RSPress chrome themes through --rp-*. See references/theming.md.
• Hand-authoring inside the plugin's generated api/ tree. That folder is build output — mount it with one _meta.json dir entry and leave the rest to the plugin (plugin-config / doc-writer).
• Assuming a missing _meta.json is an error. It is not — RSPress auto-generates an alphabetical sidebar. A wrong order usually means a missing or object-form _meta.json, not a broken build.

Reference map

Load on demand; none is required for a first page. Each answers a narrower question than this file.

• references/routing-nav.md — _meta.json array-form field reference (every type), _nav.json fields and the activeMatch dropdown pattern, the section-header flat-spine sidebar, and ordering heuristics.
• references/components.md — the built-in component catalog with exact @rspress/core/theme import paths, code-block meta (line highlight, diff), and the ::: container syntax.
• references/frontmatter.md — the frontmatter field reference, the verified pageType enum, and the home-page hero/features YAML.
• references/theming.md — the --rp-* variable families, the globalStyles hook, the :where() zero-specificity recipe, and hero-gradient / dark-mode blocks.
• references/i18n-multiversion.md — RSPress locales and multiVersion mechanics, and how they compose.
• references/deploy.md — deploying the built static site (stub — GitHub Pages, Cloudflare).