# Rspress

> Rsbuild based static site generator

## Guide

- [Introduction](/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](/guide/start/getting-started.md): Quickly create an Rspress project via CLI or manually, and learn the basic workflow of dev server startup, production build, and local preview.
- [AI](/guide/start/ai.md): To help AI better understand Rspress's features, configuration, and best practices so it can provide more accurate assistance during day-to-day development and troubleshooting, Rspress provides the following capabilities: Agent Skillsllms.txtMarkdown docsAGENTS.md
- [Conventional route](/guide/basic/conventional-route.md): Rspress uses file system routing to map file paths to URL routes, supporting custom routing with frontmatter pageType and route configuration.
- [Autogenerated navigation](/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](/guide/basic/static-assets.md): Configure site logo, favicon icons, reference images and videos in MDX files, and use the public folder for custom static resources.
- [Static site generation (SSG)](/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)](/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](/guide/basic/i18n.md): Implement document internationalization with i18n text data, language configuration, multi-language directory structure, and useI18n hook.
- [Multi version](/guide/basic/multi-version.md): Manage multi-version documentation with simple configuration, intuitive directory structure, version selector in the navbar, and version-specific search.
- [Home page](/guide/basic/home-page.md): Configure home page content via frontmatter including hero section, feature cards, and custom components.
- [Deployment](/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](/guide/basic/custom-theme.md): Customize theme via CSS variables, BEM classnames, component wrapping with slots, or ejecting built-in components for full control.
- [MDX and React components](/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](/guide/use-mdx/frontmatter.md): Define page metadata using YAML frontmatter including title, description, pageType, sidebar, outline, and more.
- [Code blocks](/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](/guide/use-mdx/link.md): Support file path and URL link formats, anchor links, custom anchor IDs, and dead link detection.
- [Container](/guide/use-mdx/container.md): Create custom containers with ::: syntax or GitHub Markdown Alerts for tip, warning, danger, note, and details blocks.
- [Overview page](/guide/advanced/overview-page.md): Enable Overview page via frontmatter overview configuration, automatically extracting information from sidebar to generate overview content.
- [Build extension](/guide/advanced/extend-build.md): Extend build capabilities with Rsbuild configuration, Rspack plugins, and custom MDX remark/rehype plugins.
- [Customizing head tags](/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](/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](/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](/plugin/system/introduction.md): The plugin system is a crucial part of Rspress, which allows you to easily extend the abilities of Rspress during the process of building a site. So, what ability can you extend with plugins? Let's take a look at the overall architecture of Rspress first. The overall architecture of Rspress is shown in the figure below: Rspress is divided into two parts: Node Side and Browser Runtime. Through the plugin system, you can easily extend the abilities of these two parts. Specifically, you can extend the ability to: Markdown/MDX compilation。You can add remark/rehype plugins to extend the compilation ability of Markdown/MDX.Add custom page. On the basis of Rspress's conventional routing, you can also add new routes through plugins, such as adding a /blog route to display a list of blogs, and the content is defined by yourself.Custom build tool behavior.In Rspress plugin, you can customize the config of the underlying build tool Rsbuild, and you can also add some Rspack or Rsbuild plugins.Extend page metadata. For each page, some metadata will be calculated inside Rspress, such as title, description, etc. You can extend the calculation logic of these metadata through plugins, and pass usePageData hook access.Insert some custom logic before and after the build process. Such as closing some event listeners after the build process ends.Add global components. Rspress internally uses React for rendering. You can flexibly extend the runtime page by defining global React components, such as adding a global BackToTop (return to top) component, adding a global side effect logic.
- [Write a plugin](/plugin/system/write-a-plugin.md): Let's inject a global component as an example to see how to define and use plugins. 1. Define a plugin A plugin is generally a function that receives some plugin params (optional) and returns an object that contains the name of the plugin and other config. In the above example, we define a plugin named plugin-example, which will define a global environment variable process.env.SLUG during the build phase, and inject a global component Example.tsx in the document. 2. Use a plugin Register plugins via plugins in rspress.config.ts: Then the Example component will be injected into the page and we can access the process.env.SLUG variable in the component.
- [Plugin API](/plugin/system/plugin-api.md): In the previous section, we introduced the basic structure of the plugin. In this section, we will introduce the API of the plugin to help you understand the abilities of the plugin in more detail. globalStyles Type：string It is used to add a global style, and the absolute path of a style file is passed in, and the usage is as follows: For example, if you want to modify the theme color, you can do so by adding a global style: globalUIComponents Type：(string | [string, object])[] It is used to add global components, passing in an array, each item in the array is the absolute path of a component, the usage is as follows: The item of globalUIComponents can be a string, which is the path of the component file, or an array, the first item is the path of the component file, and the second item is the component props, for example: When you register global components, Rspress will automatically render these React components in the theme without manually importing and using them. Through global components, you can complete many custom functions, such as: In this way, the content of the component will be rendered in the theme page, such as adding BackToTop button. In the meanwhile, you can also use the global component to register some side effects, such as: This way, side effects of components are executed in the theme page. For example, some of the following scenarios require side effects: Redirect for certain page routes.Bind click event on the img tag of the page to implement the image zoom function.When the route changes, the PV data of different pages are reported....... builderConfig Type：RsbuildConfig Rspress uses Rsbuild as the build tool. Rsbuild can be configured through builderConfig. For specific configuration options, please refer to Rsbuild. Of course, if you want to configure Rspack directly, you can also configure it through 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: It is used to modify/extend the configuration of Rspress itself. For example, if you want to modify the title of the document, you can do it through config: If it involves adding and removing a plugin, you need to implement it through addPlugin and removePlugin: beforeBuild/afterBuild Type：(config: DocConfig, isProd: boolean) => void | Promise<void> It is used to perform some operations before/after the document is built. The first parameter is the config of the document, and the second parameter is whether it is currently a production environment. The usage is as follows: markdown Type：{ remarkPlugins?: Plugin[]; rehypePlugins?: Plugin[] } It is used to extend the compilation ability of Markdown/MDX. If you want to add custom remark/rehype plugins or MDX globalComponents, you can use markdown options to achieve: 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 doc config of rspress.config.ts, and the AdditionalPage type is defined as follows: Used to add additional pages, you can return an array in the addPages function, each item in the array is a page config, you can specify the route of the page through routePath, through filepath or content to specify the content of the page. For example: addPages accepts two parameters, config is the config of the current document site, isProd indicates whether it is a production environment. routeGenerated Type：(routeMeta: RouteMeta[]) => void | Promise<void> In this hook, you can get all the route meta information. The structure of each route meta information is as follows Example: addRuntimeModules Type: (config: UserConfig, isProd: boolean) => Record<string, string> | Promise<Record<string, string>>; Used to add additional runtime modules. For example, if you want to use some compile-time information in the document, you can achieve this through addRuntimeModules: In this way, you can use the virtual-foo module in the runtime component: i18nSource Type: (source: Record<string, Record<string, string>>) => Record<string, Record<string, string>> | Promise<Record<string, Record<string, string>>> Used to add or modify internationalization (i18n) text data. You can use this hook to extend or modify the theme's i18n text. The source parameter is an object with the following structure: Where the first-level textKey is the text key name, the second-level locale is the language code (e.g., zh, en), and the value is the translated text for the corresponding language. Usage example: If your plugin provides runtime components at the same time, you can use these texts via the useI18n hook:
- [Overview](/plugin/official-plugins/overview.md)
- [@rspress/plugin-llms](/plugin/official-plugins/llms.md): Generate llms.txt related files for your Rspress site, allowing large language models to better understand your documentation site.
- [@rspress/plugin-sitemap](/plugin/official-plugins/sitemap.md): Automatically generate sitemap for SEO, which helps search engines crawl your site.
- [@rspress/plugin-client-redirects](/plugin/official-plugins/client-redirects.md): Used for client redirects.
- [@rspress/plugin-typedoc](/plugin/official-plugins/typedoc.md): Integration of TypeDoc's Rspress Plugin for Automatically Generating API Documentation for TS Modules.
- [@rspress/plugin-api-docgen](/plugin/official-plugins/api-docgen.md): The plugin is used to generate api document description automatically, powered by react-docgen-typescript and documentation.
- [@rspress/plugin-preview](/plugin/official-plugins/preview.md): Used to preview components in the code block of md(x) files, suitable for writing component library documentation.
- [@rspress/plugin-playground](/plugin/official-plugins/playground.md): Provide a real-time editable Playground to preview components in MDX file code blocks.
- [@rspress/plugin-rss](/plugin/official-plugins/rss.md): Generates RSS files for specific document pages with feed.
- [@rspress/plugin-algolia](/plugin/official-plugins/algolia.md): Based on docsearch, this plugin replaces Rspress's built-in search with algolia.
- [@rspress/plugin-twoslash](/plugin/official-plugins/twoslash.md): Integration of Twoslash's Rspress Plugin for automatically generating rich code blocks with type information.
- [Overview](/plugin/community-plugins/overview.md)

## UI

- [CSS variables](/ui/vars.md): List of Rspress built-in CSS variables for customizing brand colors, code block styles, and theme configuration.
- [Customizing page](/ui/custom-page.md): Methods for customizing page layout, global components, styles, and head tags.
- [Tailwind CSS](/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, and the Tailwind CSS configuration is consistent with Rsbuild. For more details, see: Rsbuild - Tailwind CSS v4Rsbuild - Tailwind CSS v3 Below is a guide for integrating Tailwind CSS v4 with Rspress. Install dependencies Create PostCSS config Create a postcss.config.mjs file in the root of your project: 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: Usage Now you can use Tailwind utility classes in your MDX files:
- [shadcn/ui](/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](/ui/components/index.md): Rspress built-in doc components, including commonly used UI components for documentation writing.
- [Badge](/ui/components/badge.md): Badge component for displaying small inline labels in documentation, with support for multiple types and styles.
- [Callout](/ui/components/callout.md): Callout component for displaying highlighted information blocks such as tips, warnings, and notes.
- [CodeBlockRuntime](/ui/components/code-block-runtime.md): CodeBlockRuntime component for dynamically rendering executable code blocks at runtime.
- [PackageManagerTabs](/ui/components/package-manager-tabs.md): PackageManagerTabs component for displaying installation commands across different package managers.
- [PageTabs](/ui/components/page-tabs.md): PageTabs component for creating multiple sub-tabs within a single page.
- [SourceCode](/ui/components/source-code.md): SourceCode component for rendering links to GitHub or GitLab repository source code.
- [Steps](/ui/components/steps.md): Steps component for rendering Markdown content as step-by-step instruction blocks.
- [Tabs/Tab](/ui/components/tabs.md): Tabs component for switching between multiple content panels, with group synchronization support.
- [Runtime components](/ui/runtime-components/index.md): Overview of Rspress runtime components, including Head and NoSSR for runtime use.
- [Head](/ui/runtime-components/head.md): Head component for injecting custom head content into document pages, such as meta tags and links.
- [NoSSR](/ui/runtime-components/no-ssr.md): NoSSR component for disabling server-side rendering and rendering content only on the client.
- [Built-in icons](/ui/icons/index.md): List of Rspress built-in icons and how to replace them via custom theme.
- [Layout Components](/ui/layout-components/index.md): Overview of Rspress built-in layout components, including default homepage and Overview page layouts.
- [Banner](/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](/ui/layout-components/doc-footer.md): DocFooter component for the document page footer, containing edit link, last updated time, and prev/next page navigation.
- [EditLink](/ui/layout-components/edit-link.md): EditLink component for rendering "Edit this page" link, navigating to the document source file editing page.
- [HomeBackground](/ui/layout-components/home-background.md): HomeBackground component for rendering homepage background effects and automatically setting transparent navbar.
- [HomeFeature](/ui/layout-components/home-feature.md): HomeFeature component for rendering feature grid cards below the Hero section on the homepage.
- [HomeFooter](/ui/layout-components/home-footer.md): HomeFooter component for rendering footer information at the bottom of the homepage.
- [HomeHero](/ui/layout-components/home-hero.md): HomeHero component for rendering the Hero section on the homepage, including title, description, and action buttons.
- [HomeLayout](/ui/layout-components/home-layout.md): HomeLayout component for rendering the overall homepage layout, including Hero, Features, and Footer sections.
- [LastUpdated](/ui/layout-components/last-updated.md): LastUpdated component for displaying the page's last updated time.
- [Layout](/ui/layout-components/layout.md): Layout component, serves as the layout container for the entire page, providing rich slot props for custom extensions.
- [NavTitle](/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](/ui/layout-components/overview-group.md): OverviewGroup component for rendering group cards and page lists in overview pages.
- [PrevNextPage](/ui/layout-components/prev-next-page.md): PrevNextPage component for rendering prev/next page navigation links at the bottom of the page.
- [Root](/ui/layout-components/root.md): Root component, serves as the wrapper component for the entire application, used to wrap custom Providers.
- [Tag](/ui/layout-components/tag.md): Tag component for displaying labels in sidebar or navbar, supporting built-in tags, SVG, and images.
- [Built-in hooks](/ui/hooks/index.md): Overview of Rspress built-in React hooks for accessing page data, theme state, and routing information.
- [Router hooks](/ui/hooks/router-hooks.md): Router hooks re-exported from react-router-dom for accessing navigation and location information.
- [useDark](/ui/hooks/use-dark.md): useDark hook for determining whether the current theme is dark mode.
- [useFrontmatter](/ui/hooks/use-frontmatter.md): useFrontmatter hook for accessing the current page's frontmatter metadata.
- [useI18n](/ui/hooks/use-i18n.md): useI18n hook for reading configured multilingual text in custom components.
- [useLang](/ui/hooks/use-lang.md): useLang hook for getting the current language code for multilingual rendering and route navigation.
- [~~usePageData~~](/ui/hooks/use-page-data.md): usePageData hook (deprecated) for accessing current page metadata, use usePage instead.
- [usePage](/ui/hooks/use-page.md): usePage hook for accessing metadata of the current Markdown/MDX page.
- [usePages](/ui/hooks/use-pages.md): usePages hook for accessing metadata of all pages in the site.
- [useSite](/ui/hooks/use-site.md): useSite hook for accessing the normalized site configuration from rspress.config.ts.
- [useVersion](/ui/hooks/use-version.md): useVersion hook for getting the current documentation version in multi-version docs.

## API

- [API Overview](/api/index.md)
- [Basic config](/api/config/config-basic.md)
- [Theme config](/api/config/config-theme.md): Theme config is located under themeConfig in the doc param. For example:
- [Front matter config](/api/config/config-frontmatter.md): This document introduces how to configure various properties of a page using front matter, including title, description, page type, navbar, etc. See Frontmatter for what front matter is and how to use it, and see useFrontmatter for how to access front matter in code.
- [Build config](/api/config/config-build.md)
- [Commands](/api/commands.md): Through this chapter, you can learn about the built-in commands of Rspress and how to use them.

## Blog

- [Rspress blogs](/blog/index.md)
- [Announcing Rspress 2.0](/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.