Basic config
root
- Type:
string - Default:
docs
Specifies the docs root directory. For example:
This option supports both relative and absolute paths. Relative paths are resolved from the current working directory (cwd).
You can also pass the docs root as a CLI argument:
base
- Type:
string - Default:
/
Deployment base path. For example, if you plan to deploy your site to https://foo.github.io/bar/, then you should set base to "/bar/":
siteOrigin
- Type:
string - Default:
""
The optional deployment origin of the site, for example https://foo.github.io.
Rspress uses this value together with base when generated files need absolute URLs, such as sitemap.xml, llms.txt links, or plugin outputs. The full URL concatenation order is siteOrigin + base + routePath.
If siteOrigin is not configured, Rspress uses base + routePath as the fallback.
If your site is deployed to https://foo.github.io/bar/, set siteOrigin to "https://foo.github.io" and base to "/bar/":
title
- Type:
string - Default:
"Rspress"
Site title. Rspress uses this as the HTML page title. For example:
description
- Type:
string - Default:
""
Site description. Rspress uses this as the HTML page description. For example:
icon
- Type:
string | URL - Default:
""
Site icon. Rspress uses this path as the page icon. For example:
For a normal path, Rspress resolves the icon from the public directory. You can also use a CDN URL, the file:// protocol, or a URL object for a local absolute path.
lang
- Type:
string - Default:
"en"
Default language of the site. See i18n for more details.
locales
- Type:
Locale[] - Default:
undefined
Configures the supported languages and site information for each language.
Set the top-level lang to one of these language codes to select the default language. Rspress omits the language prefix from the default language's routes.
For example:
For the complete setup, see i18n. For language-specific theme options such as nav and sidebar, see themeConfig.locales.
i18nSourcePath
- Type:
string - Default:
path.join(cwd, 'i18n.json')
Specifies the path of the i18n text data source file. By default, Rspress reads from i18n.json in the current working directory. For example:
This has the same effect as placing an i18n.json at the project root. If you also configure i18nSource, the i18nSource will be merged with and take priority over the data loaded from i18nSourcePath.
i18nSource
- Type:
Record<string, Record<string, string>> | ((value: Record<string, Record<string, string>>) => Record<string, Record<string, string>> | Promise<Record<string, Record<string, string>>>) - Default:
{}
Use this option to modify Rspress's built-in i18n text or add text for custom components. It is usually used together with useI18n.
This has the same implementation and effect as i18n.json. You can use either one. i18nSource has higher priority than i18n.json and supports functions.
The i18nSource 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.
Here is an example of modifying Rspress's built-in i18n text:
i18nSource can also be a function, for example:
Here are the built-in i18n texts in Rspress:
logo
- Type:
string | { dark: string; light: string; width?: number; height?: number } - Default:
""
Site logo. Rspress uses this path for the logo in the upper-left corner of the navbar. In the object form, optional width and height set the intrinsic dimensions (in pixels) for both images; use the source images' dimensions to reserve their aspect ratio and reduce layout shifts. For example:
Rspress resolves the logo from the public directory. You can also use a CDN URL.
You can also set different logos for dark and light mode:
logoHref
- Type:
string - Default:
/${lang}/
Custom link for the logo. By default, clicking the logo navigates to the homepage of the current language. For example:
logoText
- Type:
string - Default:
""
Site logo text. Rspress displays this text in the upper-left corner of the navbar. For example:
outDir
- Type:
string - Default:
doc_build
Custom output directory for built sites. For example:
themeDir
- Type:
string - Default:
theme
Specifies the custom theme directory. By default, Rspress uses the theme directory under the current working directory as the custom theme directory. You can use themeDir to customize it. For example:
This option supports both relative and absolute paths. Relative paths are resolved from the current working directory.
For more details on custom themes, see Custom Theme.
head
- Type:
string|[string, Record<string, string>]|(route) => string | [string, Record<string, string>] | undefined - Can be appended per page via frontmatter
Adds extra elements to the page's HTML <head> in production builds.
globalStyles
- Type:
string - Default:
undefined
Adds global styles from a style file path. For example:
sitemap
- Type:
boolean | SitemapOptions - Default:
true
Generate sitemap.xml in the output directory during production builds. This feature is built into Rspress and does not require a plugin. It also works when ssg is false. Existing sitemap files copied from the public directory are preserved. Generated URLs follow route.cleanUrls.
Configure siteOrigin so the sitemap contains absolute URLs. Rspress combines siteOrigin, base, and each page's route path:
Set sitemap: false to disable generation, or pass an options object to customize it:
The options have the following type, exported as SitemapOptions from @rspress/core:
sitemap.siteUrl
- Type:
string - Default:
siteOrigin+base, orbasewhensiteOriginis not configured
Override the deployment URL used in sitemap entries. Use an absolute URL that includes the base path, such as https://example.com/docs/. This value takes precedence over siteOrigin and base. Only HTTP(S) URLs without query strings or fragments are accepted.
If neither sitemap.siteUrl nor siteOrigin is configured, entries use base + routePath and remain relative paths. Configure either value to generate absolute sitemap URLs.
sitemap.customMaps
- Type:
Record<string, Sitemap> - Default:
{}
Override sitemap values for individual pages. Keys are route paths without base, and values override the generated loc, lastmod, changefreq, and priority. By default, lastmod is the source file's modification time. This option customizes existing pages; it does not add routes.
sitemap.defaultChangeFreq
- Type:
ChangeFreq - Default:
'monthly'
The default changefreq value for each page. Available values are 'always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', and 'never'. Use customMaps to override it for a specific page.
sitemap.defaultPriority
- Type:
Priority - Default:
'0.5'
The default priority value for each page, from '0.0' to '1.0' in increments of 0.1. The root route / uses '1.0'. Use customMaps to override it for a specific page.
mediumZoom
- Type:
boolean|{ selector?: string } - Default:
true
Controls whether image zoom is enabled. It is enabled by default; set mediumZoom to false to disable it.
Image zoom is implemented with the medium-zoom library.
Example usage:
search
- Type:
To exclude an individual page from the search index, set search: false in its frontmatter.
searchHooks
- Type:
string - Default:
undefined
Use searchHooks to add runtime hooks for search. For example:
For specific hook logic, you can read Customize Search Functions.
versioned
- Type:
boolean - Default:
true
When using multiVersion, a separate search index is created for each version by default, so that search results only include pages from the version the user is currently viewing. Set versioned to false to disable this behavior and include all versions in search results.
codeBlocks
- Type:
boolean - Default:
true
Whether to include code block content in the search index, which allows users to search code blocks.
globalUIComponents
- Type:
(string | [string, object])[] - Default:
[]
You can register global UI components through the globalUIComponents parameter, for example:
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
imgtags to implement image zoom. - Reporting page view data when the route changes.
multiVersion
- Type:
{ default: string; versions: string[] }
Enable multi-version support with multiVersion. For example:
The default parameter is the default version, and the versions parameter is the version list.
route
- Type:
Object
Custom route config.
route.include
- Type:
string[] - Default:
[]
Adds extra files to the route table. By default, only files in the docs root are included. For example:
Note: Strings in the array support glob patterns. The glob expression should be relative to the docs root and include the relevant file extensions.
For more flexible page routes and file/content mapping, we recommend using the addPages hook in a custom Rspress plugin.
route.exclude
- Type:
string[] - Default:
[]
Exclude some files from the route. For example:
Note: Strings in the array support glob patterns. The glob expression should be relative to the docs root.
route.excludeConvention
- Type:
string[] - Default:
['**/_[^_]*']
A routing convention that makes it easier to keep components in the docs directory. By default, files starting with _ are excluded.
If you really need some routes starting with _, you can adjust this rule, for example, set it to exclude only files starting with _fragment-:
route.extensions
- Type:
string[] - Default:
['.js', '.jsx', '.ts', '.tsx', '.md', '.mdx']
File extensions to include in the route table. By default, Rspress includes all 'js', 'jsx', 'ts', 'tsx', 'md', and 'mdx' files. To customize the extensions, use this option:
route.cleanUrls
- Type:
Boolean - Default:
true(falsebefore v2.1.0)
Generates URLs without file extensions. Set cleanUrls to false to keep the .html suffix.
Enabling this may require additional configuration on your hosting platform. For it to work, your server must be able to serve /foo.html when visiting /foo without a redirect.
route.cleanUrlsRedirect
- Type:
Boolean - Default:
true
When enabled, Rspress normalizes non-canonical browser URLs during client
startup, using the actual matched route as the source of truth. The target
format follows route.cleanUrls.
route.cleanUrls controls the preferred URL format used by generated links,
while route.cleanUrlsRedirect only normalizes the browser address bar.
This option runs after the requested page HTML and client runtime have loaded.
It uses history.replaceState and does not return an HTTP 301/308 response, so
it cannot fully replace a server-side or CDN canonical redirect, especially for
SEO. The hosting platform must still serve the correct Rspress page for the
requested URL variant. Prefer a server-side redirect when available.
With cleanUrls: true
Regular page routes omit the trailing slash, while directory index routes retain it.
With cleanUrls: false
Regular page routes use .html, while directory index routes use
/index.html.
For example, both /zh/guide/start/introduction.html and
/zh/guide/start/introduction/index.html match
/zh/guide/start/introduction; the final URL follows the configured
cleanUrls format without losing the locale prefix.
The canonical URL formats align with Cloudflare's HTML handling. However, Cloudflare performs server-side HTTP redirects, while this option only updates the URL in the browser.
Set cleanUrlsRedirect to false to disable browser URL normalization:
route.localeRedirect
- Type:
'auto' | 'never' | 'only-default-lang' - Default:
'auto'
Controls how first-time visitors are redirected to the closest configured locale based on window.navigator.language:
auto: Redirect from any locale to the closest configured locale.never: Disable automatic locale redirects.only-default-lang: Redirect only when the visitor opens the default locale.
This option performs the redirect in the browser. For production sites, prefer handling locale negotiation and redirects on the server or at the CDN edge when possible. This redirects visitors before HTML is delivered and does not depend on client-side JavaScript.
route.useTransitions
- Type:
Boolean - Default:
true
Enable concurrent, optimized routing for internal links rendered by Rspress' default Link component. This covers links in markdown and MDX content, as well as default theme navigation links such as sidebar items.
By default, this option is enabled. Internal page transitions are wrapped inside React's startTransition unless you explicitly set useTransitions to false. This prevents the heavy rendering of new page content from blocking user input, keeping the page responsive and interactive during navigation.
route.prefetchLink
- Type:
Boolean - Default:
true
By default, Rspress' Link component prefetches resources for the matching route when users hover over internal links, and it applies the same behavior on touch devices. This is a performance optimization. Set this option to false to disable it.
In development, link prefetching is designed to work together with dev.lazyCompilation, which Rspress enables by default. Lazy compilation improves startup speed by compiling pages only when they are visited, while link prefetching starts compiling the target route on hover to reduce the wait when the target route is opened for the first time.
Example:
ssg
- Type:
boolean | { experimentalWorker?: boolean; experimentalLoose?: boolean; } - Default:
true
Controls whether page content is rendered into HTML at build time. Rspress enables SSG by default.
Set ssg: false to generate HTML shells for client-side rendering.
Both SSG and SSG-MD require source code to compile under SSR. Code that is incompatible with SSR will cause the build to fail. You can try:
-
Make your code SSR-compatible. See Common issues and solutions in the SSG guide.
-
If your code does not support SSR, set both
ssg: falseandllms: false:rspress.config.ts
experimentalWorker
- Type:
boolean - Default:
false
When enabled, Rspress uses workers to accelerate SSG and reduce memory usage. This is suitable for large documentation sites and is based on tinypool.
experimentalExcludeRoutePaths
- Type:
(string | RegExp)[] - Default:
[]
Excludes selected pages from SSG so they use CSR HTML directly. This can help large documentation sites bypass SSG errors on a small number of pages, but it is not recommended as a default choice.
This option only affects SSG; it does not exclude pages from SSG-MD. If excluded pages are incompatible with SSR, make them SSR-compatible or set llms: false to disable SSG-MD.
replaceRules
- Type:
{ search: string | RegExp; replace: string; }[] - Default:
[]
You can set text replacement rules for the entire site through replaceRules. The rules will apply to everything including _meta.json files, frontmatter configurations, and document content and titles.
languageParity
- Type:
Object
Scans md and mdx files in the docs root to detect missing language versions and protect language parity.
languageParity.enabled
- Type:
boolean - Default:
false
Whether to enable language parity checks.
languageParity.include
- Type:
string[] - Default:
[]
Specifies which folders to check. By default, all files in the docs root are checked. Paths should be relative to each language directory. For example:
languageParity.exclude
- Type:
string[] - Default:
[]
Excludes certain folders and files from the checks.