# Rspress

> Rsbuild based static site generator

## Guide

- [Introduction](https://rspress.rs/guide/start/introduction.md): Rspress is a high-performance static site generator based on Rsbuild, featuring millisecond-level startup, AI-native SSG-MD, MDX support, full-text search, i18n and multi-version docs.
- [Quick start](https://rspress.rs/guide/start/getting-started.md): Quickly create an Rspress project via the scaffold or manual setup, and learn the basic workflow of dev server startup, production build, and local preview.
- [AI](https://rspress.rs/guide/start/ai.md): Rspress provides the following capabilities to help AI understand its features, configuration, and best practices, so it can provide more accurate assistance during day-to-day development and troubleshooting: Agent Skillsllms.txtMarkdown docsAGENTS.md
- [Conventional route](https://rspress.rs/guide/basic/conventional-route.md): Rspress uses file system routing to map file paths to URL routes, with support for frontmatter pageType and custom route configuration.
- [Autogenerated navigation](https://rspress.rs/guide/basic/auto-nav-sidebar.md): Automatically generate navbar and sidebar via _nav.json and _meta.json, supporting files, directories, section headers, custom links, and more.
- [Static assets](https://rspress.rs/guide/basic/static-assets.md): Configure site logos, favicons, images and videos in MDX files, and the public folder for custom static assets.
- [Static site generation (SSG)](https://rspress.rs/guide/basic/ssg.md): Pre-render pages to static HTML during build for faster loading, better SEO, and easy deployment to any static hosting service.
- [llms.txt (SSG-MD)](https://rspress.rs/guide/basic/ssg-md.md): Generate llms.txt and Markdown files for AI-native documentation using SSG-MD, enabling better understanding by large language models.
- [Internationalization](https://rspress.rs/guide/basic/i18n.md): Implement documentation internationalization with i18n text data, language configuration, multilingual directory structure, and the useI18n hook.
- [Multi-version](https://rspress.rs/guide/basic/multi-version.md): Manage multi-version docs with simple configuration, intuitive directory structure, a version selector in the navbar, and version-specific search.
- [Homepage](https://rspress.rs/guide/basic/home-page.md): Configure homepage content with frontmatter, including the hero section, feature cards, and custom components.
- [Deployment](https://rspress.rs/guide/basic/deploy.md): Deploy Rspress sites with production build, static resource prefix, base path configuration, and platform-specific guides for GitHub Pages, Netlify, and Vercel.
- [Custom theme](https://rspress.rs/guide/basic/custom-theme.md): Customize themes with CSS variables, BEM class names, component wrapping with slots, or ejected built-in components for full control.
- [MDX and React components](https://rspress.rs/guide/use-mdx/components.md): Use MDX to import and render React components in Markdown, with support for document fragments and custom component slots.
- [Frontmatter](https://rspress.rs/guide/use-mdx/frontmatter.md): Define page metadata using YAML frontmatter including title, description, pageType, sidebar, outline, and more.
- [Code blocks](https://rspress.rs/guide/use-mdx/code-blocks.md): Use Shiki for syntax highlighting with support for line highlighting, code titles, line numbers, word highlighting, diff display, and code folding.
- [Links](https://rspress.rs/guide/use-mdx/link.md): Support file path and URL link formats, anchor links, custom anchor IDs, and dead link detection.
- [Container](https://rspress.rs/guide/use-mdx/container.md): Create custom containers with ::: syntax or GitHub Markdown Alerts for tip, warning, danger, note, and details blocks.
- [Overview page](https://rspress.rs/guide/advanced/overview-page.md): Enable Overview page via frontmatter overview configuration, automatically extracting information from sidebar to generate overview content.
- [Build extension](https://rspress.rs/guide/advanced/extend-build.md): Extend build behavior with Rsbuild configuration, Rspack plugins, and custom MDX remark/rehype plugins.
- [Customizing head tags / SEO](https://rspress.rs/guide/advanced/custom-head.md): Adding head tags (such as meta tags) to web pages is crucial for SEO optimization and social media sharing. For example, Open Graph is a web metadata protocol that controls how pages appear when shared on social media platforms. Currently, Rspress automatically injects the following head tags:
- [Customize search functions](https://rspress.rs/guide/advanced/custom-search.md): Extend search functionality with searchHooks for keyword processing, result filtering, analytics reporting, and custom data sources.
- [Migrating from Rspress 1.x](https://rspress.rs/guide/migration/rspress-1-x.md): Complete migration guide from Rspress 1.x to V2, covering package name changes, import paths, custom themes, Shiki code highlighting, and more.

## Plugin

- [Introduction](https://rspress.rs/plugin/system/introduction.md): The plugin system is a core part of Rspress. It lets you extend Rspress during the site build process. First, let's look at the overall Rspress architecture. The overall architecture of Rspress is shown in the figure below: Rspress has two main parts: Node Side and Browser Runtime. The plugin system lets you extend both parts. Specifically, plugins can: Extend Markdown/MDX compilation by adding remark or rehype plugins.Add custom pages on top of Rspress's conventional routing, such as a /blog route that renders a custom blog list.Customize build tool behavior by modifying the underlying Rsbuild config or adding Rspack/Rsbuild plugins.Extend page metadata. Rspress calculates metadata such as title and description for each page. Plugins can extend that logic, and theme code can read the result with usePageData.Run custom logic before and after builds, such as closing event listeners after a build ends.Add global components. Since Rspress renders with React, plugins can add global React components such as a BackToTop component or global side-effect component.
- [Write a plugin](https://rspress.rs/plugin/system/write-a-plugin.md): This example injects a global component to show how to define and use plugins. 1. Define a plugin A plugin is usually a function that receives optional plugin parameters and returns an object containing the plugin name and other config. In the example above, we define a plugin named plugin-example. It defines a global environment variable, process.env.SLUG, during the build phase and injects the global component Example.tsx into the page. 2. Use a plugin Register plugins via plugins in rspress.config.ts: The Example component is then injected into the page, and the component can access process.env.SLUG.
- [Plugin API](https://rspress.rs/plugin/system/plugin-api.md): The previous section introduced the basic plugin structure. This page explains the plugin APIs and what each one can extend. globalStyles Type：string Adds a global style file. Pass the absolute path of the style file: For example, if you want to modify the theme color, you can do so by adding a global style: globalUIComponents Type：(string | [string, object])[] Adds global components. Pass an array where each item is the absolute path of a component: Each globalUIComponents item can be either a component file path string or a tuple. In the tuple form, the first item is the component file path and the second item is the component props. For example: When you register global components, Rspress automatically renders these React components in the theme without requiring manual imports. Global components can implement many custom features, such as: The component content is then rendered in the theme, for example to add a BackToTop button. You can also use a global component to register side effects: The component side effects then run in the theme. For example, side effects are useful for: Redirecting specific page routes.Binding click events on page img tags to implement image zoom.Reporting page view data when the route changes. builderConfig Type：RsbuildConfig Rspress uses Rsbuild as its build tool. Configure Rsbuild through builderConfig. For specific configuration options, see Rsbuild. To configure Rspack directly, use builderConfig.tools.rspack. See Build Config for more details. config Type：(config: DocConfig, utils: ConfigUtils) => DocConfig | Promise<DocConfig> The type of ConfigUtils is as follows: Modifies or extends the Rspress config itself. For example, use config to change the site title: To add or remove plugins, use addPlugin and removePlugin: beforeBuild/afterBuild Type：(config: DocConfig, isProd: boolean) => void | Promise<void> Runs operations before or after the docs are built. The first parameter is the resolved docs config, and the second parameter indicates whether the current build is production: markdown Type：{ remarkPlugins?: Plugin[]; rehypePlugins?: Plugin[] } Extends Markdown/MDX compilation. Use markdown to add custom remark/rehype plugins or MDX globalComponents: extendPageData Type: (pageData: PageData) => void | Promise<void> After extending the page data, you can access the page data through the usePageData hook in the theme. addPages Type: (config: UserConfig) => AdditionalPage[] | Promise<AdditionalPage[]> The config parameter is the docs config from rspress.config.ts, and the AdditionalPage type is: Adds additional pages. Return an array from addPages; each item is a page config. Use routePath to specify the page route, and use filepath or content to specify the page content. For example: addPages accepts two parameters: config is the current documentation site config, and isProd indicates whether the current build is production. routeGenerated Type：(routeMeta: RouteMeta[]) => void | Promise<void> This hook receives all route metadata. Each route metadata item has the following structure: Example: addRuntimeModules Type: (config: UserConfig, isProd: boolean) => Record<string, string> | Promise<Record<string, string>>; Adds additional runtime modules. For example, use addRuntimeModules to expose compile-time information to docs: You can then use the virtual-foo module in a runtime component: i18nSource Type: (source: Record<string, Record<string, string>>) => Record<string, Record<string, string>> | Promise<Record<string, Record<string, string>>> Adds or modifies internationalization (i18n) text data. Use this hook to extend or override the theme's i18n text. The source parameter is an object with the following structure: The first-level textKey is the text key, the second-level locale is the language code (for example, zh or en), and the value is the translated text for that language. Usage example: If your plugin also provides runtime components, read these texts with the useI18n hook:
- [Overview](https://rspress.rs/plugin/official-plugins/overview.md)
- [@rspress/plugin-llms](https://rspress.rs/plugin/official-plugins/llms.md): Generate llms.txt related files for your Rspress site so large language models can better understand your documentation.
- [@rspress/plugin-sitemap](https://rspress.rs/plugin/official-plugins/sitemap.md): Automatically generate a sitemap for SEO so search engines can crawl your site more easily.
- [@rspress/plugin-client-redirects](https://rspress.rs/plugin/official-plugins/client-redirects.md): Used for client redirects.
- [@rspress/plugin-typedoc](https://rspress.rs/plugin/official-plugins/typedoc.md): Rspress plugin for integrating TypeDoc and automatically generating API documentation for TypeScript modules.
- [@rspress/plugin-api-docgen](https://rspress.rs/plugin/official-plugins/api-docgen.md): This plugin generates API reference content automatically, powered by react-docgen-typescript and documentation.
- [@rspress/plugin-preview](https://rspress.rs/plugin/official-plugins/preview.md): Preview components from code blocks in MDX files. This is useful for component library documentation.
- [@rspress/plugin-playground](https://rspress.rs/plugin/official-plugins/playground.md): Provides a live editable playground for previewing components in MDX code blocks.
- [@rspress/plugin-rss](https://rspress.rs/plugin/official-plugins/rss.md): Generates RSS files for selected documentation pages with feed.
- [@rspress/plugin-algolia](https://rspress.rs/plugin/official-plugins/algolia.md): This plugin replaces Rspress's built-in search with Algolia through DocSearch.
- [@rspress/plugin-twoslash](https://rspress.rs/plugin/official-plugins/twoslash.md): Integrates Twoslash with Rspress to generate rich TypeScript code blocks with type information.
- [Overview](https://rspress.rs/plugin/community-plugins/overview.md)
- [rspress-plugin-typesense](https://rspress.rs/plugin/community-plugins/typesense.md): This plugin replaces Rspress's built-in search with Typesense, an open-source, typo-tolerant search engine. The plugin automatically indexes your documentation during the build process (rspress build) and provides a highly-optimized search experience with support for Rspress multi-versioning and internationalization.

## UI

- [CSS variables](https://rspress.rs/ui/vars.md): List of Rspress built-in CSS variables for customizing brand colors, code block styles, and theme configuration.
- [Customizing page](https://rspress.rs/ui/custom-page.md): Methods for customizing page layout, global components, styles, and head tags.
- [Tailwind CSS](https://rspress.rs/ui/tailwindcss.md): Tailwind CSS is a utility-first CSS framework for rapidly building custom user interfaces. It can be used with MDX files in Rspress to help you style your documentation more efficiently, for example: Rspress is built on Rsbuild, so Tailwind CSS v4 can be integrated with the same Rsbuild plugin recommended by Rsbuild. For more details, see: Rsbuild - Tailwind CSS v4Rsbuild - Tailwind CSS v3Rsbuild - Tailwind CSS plugin Below is a guide for integrating Tailwind CSS v4 with Rspress. Install dependencies Create Tailwind CSS file Create a tailwind.css file in the root of your project: Configure Rspress In your rspress.config.ts, use the globalStyles option to import the Tailwind CSS file: If your project already has a PostCSS setup, you can also follow the Rsbuild guide to use @tailwindcss/postcss instead. Usage Now you can use Tailwind utility classes in your MDX files:
- [shadcn/ui](https://rspress.rs/ui/shadcn-ui.md): shadcn/ui is a collection of reusable components built with Radix UI / Base UI and Tailwind CSS. This guide covers how to use shadcn/ui components in your Rspress documentation site. Make sure you have already set up Tailwind CSS in your project before proceeding. Configure path aliases Add paths to the compilerOptions in your tsconfig.json so that shadcn/ui components can be resolved correctly: Create components.json and utility function Since shadcn init cannot automatically detect the Rspress framework, you need to follow the manual installation approach to create the configuration files. Create a components.json file in your project root to configure the shadcn/ui CLI: Then install the dependencies and create the utility function: Add components Use the shadcn CLI to add the components you need. For example, to add a Button: Usage in MDX Import and use components in your MDX files:
- [Doc Components](https://rspress.rs/ui/components/index.md): Rspress built-in doc components, including commonly used UI components for documentation writing.
- [Badge](https://rspress.rs/ui/components/badge.md): Badge component for displaying small inline labels in documentation, with support for multiple types and styles.
- [Callout](https://rspress.rs/ui/components/callout.md): Callout component for displaying highlighted information blocks such as tips, warnings, and notes.
- [CodeBlockRuntime](https://rspress.rs/ui/components/code-block-runtime.md): CodeBlockRuntime component for dynamically rendering executable code blocks at runtime.
- [PackageManagerTabs](https://rspress.rs/ui/components/package-manager-tabs.md): PackageManagerTabs component for displaying installation commands across different package managers.
- [PageTabs](https://rspress.rs/ui/components/page-tabs.md): PageTabs component for creating multiple sub-tabs within a single page.
- [Prompt](https://rspress.rs/ui/components/prompt.md): Prompt component for standout, copyable agent instructions or custom MDX content.
- [SourceCode](https://rspress.rs/ui/components/source-code.md): SourceCode component for rendering links to GitHub or GitLab repository source code.
- [Steps](https://rspress.rs/ui/components/steps.md): Steps component for rendering Markdown content as step-by-step instruction blocks.
- [Tabs/Tab](https://rspress.rs/ui/components/tabs.md): Tabs component for switching between multiple content panels, with group synchronization support.
- [Runtime components](https://rspress.rs/ui/runtime-components/index.md): Overview of Rspress runtime components, including Head, NoSSR, and BrowserOnly for runtime use.
- [BrowserOnly](https://rspress.rs/ui/runtime-components/browser-only.md): BrowserOnly component for rendering content only in the browser after hydration.
- [Head](https://rspress.rs/ui/runtime-components/head.md): Head component for injecting custom head content into doc pages, such as meta tags and links.
- [NoSSR](https://rspress.rs/ui/runtime-components/no-ssr.md): NoSSR component for disabling server-side rendering and rendering content only on the client.
- [Built-in icons](https://rspress.rs/ui/icons/index.md): List of Rspress built-in icons and how to replace them via custom theme.
- [Layout Components](https://rspress.rs/ui/layout-components/index.md): Overview of Rspress built-in layout components, including default homepage and Overview page layouts.
- [Banner](https://rspress.rs/ui/layout-components/banner.md): Banner notification component for displaying notification messages at the top of the page, with link navigation and close functionality.
- [DocFooter](https://rspress.rs/ui/layout-components/doc-footer.md): DocFooter component for the doc page footer, containing the edit link, last updated time, and prev/next page navigation.
- [EditLink](https://rspress.rs/ui/layout-components/edit-link.md): EditLink component for rendering "Edit this page" link, navigating to the document source file editing page.
- [getCustomMDXComponent](https://rspress.rs/ui/layout-components/get-custom-mdx-component.md): getCustomMDXComponent theme API for overriding default MDX element renderers in Rspress doc layouts.
- [HomeBackground](https://rspress.rs/ui/layout-components/home-background.md): HomeBackground component for rendering homepage background effects and automatically setting transparent navbar.
- [HomeFeature](https://rspress.rs/ui/layout-components/home-feature.md): HomeFeature component for rendering feature grid cards below the Hero section on the homepage.
- [HomeFooter](https://rspress.rs/ui/layout-components/home-footer.md): HomeFooter component for rendering footer information at the bottom of the homepage.
- [HomeHero](https://rspress.rs/ui/layout-components/home-hero.md): HomeHero component for rendering the Hero section on the homepage, including title, description, and action buttons.
- [HomeLayout](https://rspress.rs/ui/layout-components/home-layout.md): HomeLayout component for rendering the overall homepage layout, including Hero, Features, and Footer sections.
- [LastUpdated](https://rspress.rs/ui/layout-components/last-updated.md): LastUpdated component for displaying the page's last updated time and author.
- [Layout](https://rspress.rs/ui/layout-components/layout.md): Layout component, serves as the layout container for the entire page, providing rich slot props for custom extensions.
- [NavTitle](https://rspress.rs/ui/layout-components/nav-title.md): This component is part of the navbar. NavTitle renders the site Logo and title in the top-left corner of the navbar.
- [OverviewGroup](https://rspress.rs/ui/layout-components/overview-group.md): OverviewGroup component for rendering group cards and page lists in overview pages.
- [PrevNextPage](https://rspress.rs/ui/layout-components/prev-next-page.md): PrevNextPage component for rendering prev/next page navigation links at the bottom of the page.
- [Root](https://rspress.rs/ui/layout-components/root.md): Root component, serves as the wrapper component for the entire application, used to wrap custom Providers.
- [Tag](https://rspress.rs/ui/layout-components/tag.md): Tag component for displaying labels in sidebar or navbar, supporting built-in tags, SVG, and images.
- [Built-in hooks](https://rspress.rs/ui/hooks/index.md): Overview of Rspress built-in React hooks for accessing page data, theme state, and routing information.
- [Router hooks](https://rspress.rs/ui/hooks/router-hooks.md): Router hooks re-exported from react-router-dom for accessing navigation and location information.
- [useDark](https://rspress.rs/ui/hooks/use-dark.md): useDark hook for determining whether the current theme is dark mode.
- [useFrontmatter](https://rspress.rs/ui/hooks/use-frontmatter.md): useFrontmatter hook for accessing the current page's frontmatter metadata.
- [useHead](https://rspress.rs/ui/hooks/use-head.md): useHead hook for declaring document head tags in React components and layouts.
- [useI18n](https://rspress.rs/ui/hooks/use-i18n.md): useI18n hook for reading configured multilingual text in custom components.
- [useLang](https://rspress.rs/ui/hooks/use-lang.md): useLang hook for getting the current language code for multilingual rendering and route navigation.
- [usePageData](https://rspress.rs/ui/hooks/use-page-data.md): usePageData hook (deprecated) for accessing current page metadata, use usePage instead.
- [usePage](https://rspress.rs/ui/hooks/use-page.md): usePage hook for accessing metadata of the current Markdown/MDX page.
- [usePages](https://rspress.rs/ui/hooks/use-pages.md): usePages hook for accessing metadata of all pages in the site.
- [useSite](https://rspress.rs/ui/hooks/use-site.md): useSite hook for accessing the normalized site configuration from rspress.config.ts.
- [useVersion](https://rspress.rs/ui/hooks/use-version.md): useVersion hook for getting the current documentation version in multi-version docs.

## API

- [API Overview](https://rspress.rs/api/index.md)
- [Basic config](https://rspress.rs/api/config/config-basic.md)
- [Theme config](https://rspress.rs/api/config/config-theme.md): Theme configuration is defined under themeConfig. For example:
- [Frontmatter config](https://rspress.rs/api/config/config-frontmatter.md): This page explains how to configure page-level properties with frontmatter, including title, description, page type, and navbar visibility. See Frontmatter for the frontmatter syntax, and useFrontmatter for accessing frontmatter in code.
- [Build config](https://rspress.rs/api/config/config-build.md)
- [Commands](https://rspress.rs/api/commands.md): This page introduces the built-in Rspress commands and their common options. For dev, build, and preview, the optional [root] argument specifies the docs root directory. If omitted, Rspress uses root from the config file, or docs in the current directory when root is not configured.

## Blog

- [Rspress blogs](https://rspress.rs/blog/index.md)
- [Announcing Rspress 2.0](https://rspress.rs/blog/rspress-v2.md): Rspress 2.0 is officially released, featuring a brand new theme, AI-native SSG-MD and llms.txt generation, Shiki code highlighting, lazyCompilation, an improved documentation development experience.