Basic Config#

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

import { defineConfig } from 'rspress/config';

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

title#

• Type: string
• Default: "Island"

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

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:

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:

import { defineConfig } from 'rspress/config';

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

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

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:

import { defineConfig } from 'rspress/config';

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

The framework 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:

import { defineConfig } from 'rspress/config';

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

outDir#

• Type: string
• Default: doc_build

Custom output directory for built sites. for example:

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:

import { defineConfig } from 'rspress/config';

export default defineConfig({
  locales: [
    {
      lang: 'en-US',
      label: 'English',
      title: 'Doc Tools',
      description: 'Doc Tools',
    },
    {
      lang: 'zh-CN',
      label: '简体中文',
      title: '文档框架',
      description: '文档框架',
    },
  ],
});

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:

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: { searchHooks: string }

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

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

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

In searchHooks.ts, you need to export the onSearch function, which will be called every time a search is performed. The input parameter is the search keyword, and you can customize the search interception logic here, for example:

// Supports async function
export async function onSearch(query: string) {
  // Execute custom logic, such as logging reporting
  console.log(query);
}

globalUIComponents#

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

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

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:

import { defineConfig } from 'rspress/config';

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

When you register global components, the framework 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:

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:

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:

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/**/*'],
  },
});

Note: The strings in the array support glob patterns.

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.

route.extensions#

• Type: string[]
• Default: []

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: ['.jsx', '.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,
  },
});