rspress-custom-theme

# Rspress Custom Theme Guide for customizing Rspress (v2) themes. Rspress offers four levels of customization, from lightest to heaviest. Always prefer the lightest approach that meets the requirement — lighter approaches are more maintainable and survive Rspress upgrades. ## Workflow 1. **Understand the user's goal** — what do they want to change? (colors, layout, inject content, replace a component entirely?) 2. **Pick the right level** using the decision flow below 3. **Set up `theme/index.tsx`** if needed (Levels 1A, 3, 4 all need it) 4. **Implement** following the patterns in this skill and reference files 5. **Verify** the user's Rspress version is v2 (imports use `@rspress/core/*` not `rspress/*`) ## Decision Flow | User wants to... | Level | Approach | | ---------------------------------------------------------------- | ----- | --------------------------- | | Change brand colors, fonts, spacing, shadows | 1 | CSS variables | | Adjust a specific component's style (borders, padding, etc.) | 2 | BEM class overrides | | Add content around existing components (banners, footers, logos) | 3 | Layout slots (wrap) | | Override MDX rendering (custom `<h1>`, `<code>`, etc.) | 3 | `components` slot | | Wrap the app in a provider (state, analytics, auth) | 4 | Eject `Root` | | Replace built-in icons (logo, GitHub, search, etc.) | — | Icon re-export | | Completely replace a built-in component | 4 | Eject that component | | Add a global floating component (back-to-top, chat widget) | — | `globalUIComponents` config | | Control page layout structure (hide sidebar, blank page) | — | Frontmatter `pageType` | --- ## theme/index.tsx — The Entry Point Levels 1A, 3, and 4 all require a `theme/index.tsx` file in the project root (sibling to `docs/`). This is the single entry point for all theme customizations: ```text project/ ├── docs/ ├── theme/ │ ├── index.tsx # Theme entry — re-exports + overrides │ ├── index.css # CSS variable / BEM overrides (optional) │ └── components/ # Ejected components (Level 4) └── rspress.config.ts ``` Minimal setup: ```tsx // theme/index.tsx import './index.css'; // optional export * from '@rspress/core/theme-original'; ``` **Critical import rule**: Inside `theme/` files, always import from `@rspress/core/theme-original`. The path `@rspress/core/theme` resolves to your own `theme/index.tsx`, which causes circular imports. (In `docs/` MDX files, `@rspress/core/theme` is fine — it correctly points to your custom theme.) --- ## Level 1: CSS Variables Override CSS custom properties for brand colors, backgrounds, text, code blocks, and more. **Option A** — `theme/index.css` (use when you also have component overrides in `theme/index.tsx`): ```css /* theme/index.css */ :root { --rp-c-brand: #7c3aed; --rp-c-brand-light: #8b5cf6; --rp-c-brand-dark: #6d28d9; } .dark { --rp-c-brand: #a78bfa; } ``` **Option B** — `globalStyles` (use when you only need CSS changes, no component overrides): ```ts // rspress.config.ts export default defineConfig({ globalStyles: path.join(__dirname, 'styles/custom.css'), }); ``` > **Full variable list**: Read `references/css-variables.md` for all available CSS variables with light/dark defaults. --- ## Level 2: BEM Class Overrides All built-in components follow BEM naming: `.rp-[component]__[element]--[modifier]`. Common targets: `.rp-nav`, `.rp-link`, `.rp-tabs`, `.rp-codeblock`, `.rp-codeblock__title`, `.rp-nav-menu__item--active`. Use these in your CSS file for targeted style changes when CSS variables aren't granular enough. --- ## Level 3: Wrap (Layout Slots) Inject content at specific positions in the layout without replacing built-in components. Override `Layout` in `theme/index.tsx`: ```tsx // theme/index.tsx import { Layout as OriginalLayout } from '@rspress/core/theme-original'; export * from '@rspress/core/theme-original'; export function Layout() { return ( <OriginalLayout beforeNavTitle={<MyLogo />} bottom={<CustomFooter />} /> ); } ``` Use runtime hooks inside slot components — import from `@rspress/core/runtime`: `useDark()`, `useLang()`, `useVersion()`, `usePage()`, `useSite()`, `useFrontmatter()`, `useI18n()`. > **All slots & examples**: Read `references/layout-slots.md` for the complete slot list and usage patterns including i18n and MDX component overrides. --- ## Level 4: Eject Copy a built-in component's source for full replacement. Only use when wrap/slots cannot achieve the customization. ```bash rspress eject # list available components rspress eject DocFooter # eject to theme/components/DocFooter/ ``` Then re-export in `theme/index.tsx` (named export takes precedence over the wildcard): ```tsx export * from '@rspress/core/theme-original'; export { DocFooter } from './components/DocFooter'; ``` > **Component list & patterns**: Read `references/eject-components.md` for available components, workflow, and common patterns. --- ## Custom Icons Rspress has 27 built-in icons used across the UI. You can replace any of them by re-exporting your own icon component with the same name — no ejection needed. This uses the same `theme/index.tsx` mechanism: your named export takes precedence over the wildcard re-export. **Icon type**: Each icon is a React component or a URL string: ```ts import type { FC, SVGProps } from 'react'; type Icon = FC<SVGProps<SVGSVGElement>> | string; ``` **Example 1** — Replace an icon with a custom SVG component: ```tsx // theme/index.tsx export * from '@rspress/core/theme-original'; // Named export overrides the wildcard — replaces the GitHub icon site-wide export const IconGithub = (props: React.SVGProps<SVGSVGElement>) => ( <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" {...props}> <path d="M12 2C6.477 2 2 6.484 2 12.017c0 ..." fill="currentColor" /> </svg> ); ``` **Example 2** — Use an SVGR import: ```tsx // theme/index.tsx export * from '@rspress/core/theme-original'; import CustomGithubIcon from './icons/github.svg?react'; export const IconGithub = CustomGithubIcon; ``` **Using `SvgWrapper` in MDX or custom components**: ```mdx import { SvgWrapper, IconGithub } from '@rspress/core/theme'; <SvgWrapper icon={IconGithub} width={24} height={24} /> ``` **Available icons**: `IconArrowDown`, `IconArrowRight`, `IconClose`, `IconCopy`, `IconDeprecated`, `IconDown`, `IconEdit`, `IconEmpty`, `IconExperimental`, `IconExternalLink`, `IconFile`, `IconGithub`, `IconGitlab`, `IconHeader`, `IconJump`, `IconLink`, `IconLoading`, `IconMenu`, `IconMoon`, `IconScrollToTop`, `IconSearch`, `IconSmallMenu`, `IconSuccess`, `IconSun`, `IconTitle`, `IconWrap`, `IconWrapped`. > **Source**: See the [icons source](https://github.com/web-infra-dev/rspress/blob/main/packages/core/src/theme/icons.ts) for default implementations. --- ## Global UI Components For components that should render on every page without theme overrides: ```ts // rspress.config.ts export default defineConfig({ globalUIComponents: [ path.join(__dirname, 'components', 'BackToTop.tsx'), [ path.join(__dirname, 'components', 'Analytics.tsx'), { trackingId: '...' }, ], ], }); ``` --- ## Page Types Control layout per page via frontmatter `pageType`: | Value | Description | | ---------- | ------------------------------------- | | `home` | Home page with navbar | | `doc` | Standard doc with sidebar and outline | | `doc-wide` | Doc without sidebar/outline | | `custom` | Custom content with navbar only | | `blank` | Custom content without navbar | | `404` | 404 error page | Fine-grained: set `navbar: false`, `sidebar: false`, `outline: false`, `footer: false` individually. --- ## Common Pitfalls - **Circular import**: Using `@rspress/core/theme` instead of `@rspress/core/theme-original` in `theme/` files — causes infinite loop. - **Eject over-use**: Ejecting when a Layout slot or CSS variable would suffice — creates upgrade burden. - **Missing re-export**: Forgetting `export * from '@rspress/core/theme-original'` in `theme/index.tsx` — breaks all un-overridden components. - **v1 imports**: Using `rspress/theme` or `@rspress/theme-default` — these are v1 paths. v2 uses `@rspress/core/theme-original`. ## Reference - Custom theme guide: <https://rspress.rs/guide/basic/custom-theme> - CSS variables: <https://rspress.rs/ui/vars> - Layout component: <https://rspress.rs/ui/layout-components/layout> - Built-in icons: <https://rspress.rs/ui/icons/> - Built-in hooks: <https://rspress.rs/ui/hooks/> - CLI commands (eject): <https://rspress.rs/api/commands>