English

Basic config

root

Type: string
Default: docs

Specifies the document root directory. For example:

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  root: 'docs',
});

This config supports both relative and absolute paths, with relative paths being relative to the current working directory(cwd).

Of course, in addition to specifying the document root directory through the config file, you can also specify it through command line parameters, such as:

rspress dev docs
rspress build docs

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/":

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  base: '/bar/',
});

title

Type: string
Default: "Rspress"

Site title. This parameter will be used as the title of the HTML page. For example:

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  title: 'My Site',
});

description

Type: string
Default: ""

Site description. This will be used as the description of the HTML page. For example:

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  description: 'My Site Description',
});

icon

Type: string
Default: ""

Site icon. This path will be used as the icon path for the HTML page. For example:

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  icon: '/favicon.ico',
});

Rspress will find your icon in the public directory, of course you can also set it to a CDN address.

lang

Type: string
Default: ""

Default language of the site. See Internationalization for more details.

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  lang: 'en',
  locales: [
    {
      lang: 'en',
      // ...
    },
    {
      lang: 'zh',
      // ...
    },
  ],
});

logo

Type: string | { dark: string; light: string }
Default: ""

Site logo. This path will be used as the logo path in the upper left corner of the navbar. For example:

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  logo: '/logo.png',
});

Rspress will find your icon in the public directory, you can also set it to a CDN address.

Of course you can set different logos for dark/light mode:

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  logo: {
    dark: '/logo-dark.png',
    light: '/logo-light.png',
  },
});

logoText

Type: string
Default: ""

Site logo Text. This text will be used as the logo text in the upper left corner of the navbar. For example:

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  logoText: 'rspress',
});

outDir

Type: string
Default: doc_build

Custom output directory for built sites. for example:

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  outDir: 'doc_build',
});

locales

Type: Locale[]

export interface Locale {
  lang: string;
  label: string;
  title?: string;
  description?: string;
}

I18n config of the site. for example:

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  locales: [
    {
      lang: 'en-US',
      label: 'English',
      title: 'My Site',
      description: 'My site description',
    },
    {
      lang: 'zh-CN',
      label: '简体中文',
      title: '站点标题',
      description: '站点描述',
    },
  ],
});

head

Type: string | [string, Record<string, string>] | (route) => string | [string, Record<string, string>] | undefined
Can be appended per page via frontmatter

Used to set additional elements rendered in the <head> tag of the page's HTML in production mode.

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  // ... other user config
  head: [
    '<meta name="author" content="John Doe">',
    // or
    ['meta', { name: 'author', content: 'John Doe' }],
    // [htmlTag, { attrName: attrValue, attrName2: attrValue2 }]
    // or
    (route) => {
      if (route.routePath.startsWith('/jane/')) return "<meta name='author' content='Jane Doe'>";
      if (route.routePath.startsWith('/john/')) return ['meta', { name: 'author', content: 'John Doe' }];
      \\ or even skip returning anything
      return undefined;
    }
  ]
});

mediumZoom

Type: boolean | { selector?: string }
Default: true

Whether to enable the image zoom function. It is enabled by default, you can disable it by setting mediumZoom to false.

The bottom layer is implemented using the medium-zoom library.

Example usage:

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  // Turn off image zoom
  mediumZoom: false,
  // Configure the CSS selector to customize the picture to be zoomed, the default is '.rspress-doc img'
  mediumZoom: {
    selector: '.rspress-doc img',
  },
});

search

Type:

type SearchOptions = {
  searchHooks?: string;
  versioned?: boolean;
  codeBlocks?: boolean;
};

searchHooks

Type: string
Default: undefined

You can add search runtime hooks logic through the searchHooks parameter, for example:

rspress.config.ts

import { defineConfig } from 'rspress/config';
import path from 'path';

export default defineConfig({
  search: {
    searchHooks: path.join(__dirname, 'searchHooks.ts'),
  },
});

For specific hook logic, you can read Customize Search Functions.

versioned

Type: boolean
Default: false

If you are using multiVersion, the versioned parameter allows you to create a separate search index for each version of your documentation. When enabled, the search will only query the index corresponding to the currently selected version.

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  search: {
    versioned: true,
  },
});

codeBlocks

Type: boolean
Default: true

Whether to include code block content in the search index, which allows users to search code blocks.

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  search: {
    codeBlocks: false,
  },
});

globalUIComponents

Type: (string | [string, object])[]
Default: []

You can register global UI components through the globalUIComponents parameter, for example:

rspress.config.ts

import { defineConfig } from 'rspress/config';
import path from 'path';

export default defineConfig({
  globalUIComponents: [path.join(__dirname, 'components', 'MyComponent.tsx')],
});

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:

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  globalUIComponents: [
    [
      path.join(__dirname, 'components', 'MyComponent.tsx'),
      {
        foo: 'bar',
      },
    ],
  ],
});

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:

compUi.tsx

import React from 'react';

// Need a default export
// The props comes from your config
export default function PluginUI(props?: { foo: string }) {
  return <div>This is a global layout component</div>;
}

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:

compSideEffect.tsx

import { useEffect } from 'react';
import { useLocation } from 'rspress/runtime';

// Need a default export
export default function PluginSideEffect() {
  const { pathname } = useLocation();
  useEffect(() => {
    // Executed when the component renders for the first time
  }, []);

  useEffect(() => {
    // Executed when the route changes
  }, [pathname]);
  return null;
}

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.
......

multiVersion

Type: { default: string; versions: string[] }

You can enable multi-version support through the multiVersion parameter, for example:

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  multiVersion: {
    default: 'v1',
    versions: ['v1', 'v2'],
  },
});

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: []

Add some extra files in the route. By default, only the files in the document root directory will be included in the route. If you want to add some extra files to the route, you can use this option. For example:

import { defineConfig } from 'rspress/config';

export default defineConfig({
  route: {
    include: ['other-dir/**/*.{md,mdx}'],
  },
});

Note: The strings in the array support glob patterns, the glob expression should be based on the root directory of the document, with the corresponding extensions suffix.

NOTE

We recommend using addPages hook in a custom Rspress plugin to add some additional files to the route, so that the page route and file path/content can be specified more flexibly and reasonably.

route.exclude

Type: string[]
Default: []

Exclude some files from the route. For example:

import { defineConfig } from 'rspress/config';

export default defineConfig({
  route: {
    exclude: ['custom.tsx', 'component/**/*'],
  },
});

Note: The strings in the array support glob patterns, the glob expression should be based on the root directory of the document.

route.extensions

Type: string[]
Default: ['.js', '.jsx', '.ts', '.tsx', '.md', '.mdx']

The extensions of the files that will be included in the route. By default, Rspress will include all 'js', 'jsx', 'ts', 'tsx', 'md', 'mdx' files in the route. If you want to customize the extensions, you can use this option. For example:

import { defineConfig } from 'rspress/config';

export default defineConfig({
  route: {
    extensions: ['.md', '.mdx'],
  },
});

route.cleanUrls

Type: Boolean
Default: false

Generate url without suffix when cleanUrls is true for shorter url link.

import { defineConfig } from 'rspress/config';

export default defineConfig({
  route: {
    cleanUrls: true,
  },
});

ssg

Type: boolean | { fallback?: false | 'csr' }
Default: true

Whether to enable static site generation. Rspress enable it by default to generate CSR outputs and SSG outputs.

If your document site is only required to be used in CSR scenarios, you can set ssg to false, and Rspress will only generate CSR outputs.

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  ssg: false,
});

If you do not strictly require SSG generation in your scenario, you can set ssg to { fallback: 'csr' }. When SSG fails, it will fallback to generate only CSR outputs.

rspress.config.ts

export default {
  ssg: {
    fallback: 'csr',
  },
};

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.

rspress.config.ts

export default {
  replaceRules: [
    {
      search: /foo/g,
      replace: 'bar',
    },
  ],
};

languageParity

Type: Object

Scans the md and mdx files in the document root directory to detect missing language versions, protect language parity.

languageParity.enable

Type: boolean
Default: false

Whether to enable language parity checks.

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  languageParity: {
    enabled: true,
  },
});

languageParity.include

Type: string[]
Default: []

Specifies the folders to be checked, defaulting to all files in the document root directory. Paths should be relative to each language directory. For example:

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  languageParity: {
    // `posts/foods` and `articles` folders under the zh/en language directories
    include: ['posts/foods', 'articles'],
  },
});

languageParity.exclude

Type: string[]
Default: []

Excludes certain folders and files from the checks.

rspress.config.ts

import { defineConfig } from 'rspress/config';

export default defineConfig({
  languageParity: {
    exclude: ['excluded-directory', 'articles/secret.md'],
  },
});

#Basic config

#root

#base

#title

#description

#icon

#lang

#logo

#logoText

#outDir

#locales

#head

#mediumZoom

#search

#searchHooks

#versioned

#codeBlocks

#globalUIComponents

#multiVersion

#route

#route.include

#route.exclude

#route.extensions

#route.cleanUrls

#ssg

#replaceRules

#languageParity

#languageParity.enable

#languageParity.include

#languageParity.exclude

Basic config

root

base

title

description

icon

lang

logo

logoText

outDir

locales

head

mediumZoom

search

searchHooks

versioned

codeBlocks

globalUIComponents

multiVersion

route

route.include

route.exclude

route.extensions

route.cleanUrls

ssg

replaceRules

languageParity

languageParity.enable

languageParity.include

languageParity.exclude