#Build config

#builderConfig

• Type: RsbuildConfig

Used to customize the configurations of Rsbuild. For detailed configurations, please refer to Rsbuild - Config.

• Example: Use resolve.alias to configure path aliases:

export default defineConfig({
  builderConfig: {
    resolve: {
      alias: {
        '@common': './src/common',
      },
    },
  },
});

• Example: Use tools.rspack to modify the Rspack configuration, such as registering a webpack or Rspack plugin:

export default defineConfig({
  builderConfig: {
    tools: {
      rspack: async (config) => {
        const { default: ESLintPlugin } = await import('eslint-webpack-plugin');
        config.plugins?.push(new ESLintPlugin());
        return config;
      },
    },
  },
});

#builderConfig.plugins

• Type: RsbuildPlugin[]

To register Rsbuild plugins.

You can leverage Rsbuild's extensive plugin ecosystem to enhance and extend your build capabilities.

• Example: Support Vue SFC through @rsbuild/plugin-vue

import { defineConfig } from '@rspress/core';
import { pluginVue } from '@rsbuild/plugin-vue';

export default defineConfig({
  builderConfig: {
    plugins: [pluginVue()],
  },
});

• Example: Add Google analytics through rsbuild-plugin-google-analytics.

import { defineConfig } from '@rspress/core';
import { pluginGoogleAnalytics } from 'rsbuild-plugin-google-analytics';

export default defineConfig({
  builderConfig: {
    plugins: [
      pluginGoogleAnalytics({
        // replace this with your Google tag ID
        id: 'G-xxxxxxxxxx',
      }),
    ],
  },
});

• Example: Add Open Graph meta tags through rsbuild-plugin-open-graph.

import { defineConfig } from '@rspress/core';
import { pluginOpenGraph } from 'rsbuild-plugin-open-graph';

export default defineConfig({
  builderConfig: {
    plugins: [
      pluginOpenGraph({
        title: 'My Website',
        type: 'website',
        // ...options
      }),
    ],
  },
});

You can also override the built-in plugin @rsbuild/plugin-react and customize the plugin options.

For example:

import { defineConfig } from '@rspress/core';
import { pluginReact } from '@rsbuild/plugin-react';

export default defineConfig({
  builderConfig: {
    plugins: [
      pluginReact({
        // ...options
      }),
    ],
  },
});

#Default config

If you need to view the default Rspack or Rsbuild configs, you can add the DEBUG=rsbuild parameter when running the rspress dev or rspress build command:

DEBUG=rsbuild rspress dev

After execution, the rsbuild.config.js file is created in the doc_build directory, which contains the complete builderConfig.

Please refer to Rsbuild - Debug Mode for more information on how to debug the Rsbuild.

#markdown

Configure MDX-related compilation abilities.

#markdown.remarkPlugins

• Type: Array
• Default: []

Configure the remark plugins. for example:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    remarkPlugins: [
      [
        require('remark-autolink-headings'),
        {
          behavior: 'wrap',
        },
      ],
    ],
  },
});

#markdown.rehypePlugins

• Type: Array

Configure the rehype plugin. for example:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    rehypePlugins: [
      [
        require('rehype-autolink-headings'),
        {
          behavior: 'wrap',
        },
      ],
    ],
  },
});

#markdown.shiki

• Type: import('@shikijs/rehype').RehypeShikiOptions

• Default:

const cssVariablesTheme = createCssVariablesTheme({
  name: 'css-variables',
  variablePrefix: '--shiki-',
  variableDefaults: {},
  fontStyle: true,
});
const shikiOptions = {
  theme: cssVariablesTheme,
  defaultLanguage: 'txt',
  lazy: true,
  langs: ['tsx', 'ts', 'js'],
  addLanguageClass: true,
};

Configure Shiki-related options. For details, see RehypeShikiOptions.

#markdown.link

• Type:

export type RemarkLinkOptions = {
  checkDeadLinks?:
    | boolean
    | { excludes: string[] | ((url: string) => boolean) };
  autoPrefix?: boolean;
};

• Default: { checkDeadLinks: true, autoPrefix: true }

Configure link-related options.

#markdown.link.checkDeadLinks

• Type: boolean | { excludes: string[] | ((url: string) => boolean) }
• Default: true

After enabling this configuration, Rspress will check the links in the document based on convention routing. If an inaccessible link occurs, the build will throw an error and exit.

If there is a misjudgment of links, you can ignore the error through the excludes configuration:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    link: {
      checkDeadLinks: {
        excludes: ['/guide/getting-started', '/llms.txt'],
      },
    },
  },
});

#markdown.link.autoPrefix

• Type: boolean
• Default: true

After enabling this config, Rspress will automatically add prefixes to links in documents based on the conventional routing about i18n and Multi version.

If a user writes a link [](/guide/getting-started) in docs/zh/guide/index.md, Rspress will automatically convert it to [](/zh/guide/getting-started).

#markdown.showLineNumbers

• Type: boolean

Whether to display the line number of the code block. Defaults to false.

When enabled globally, you can use lineNumbers=false in the code block meta to disable line numbers for a specific block. Conversely, when disabled globally, you can use lineNumbers or lineNumbers=true to enable line numbers for a specific block. See Show code line numbers for details.

#markdown.defaultWrapCode

• Type: boolean

Whether to enable long code line wrapping display by default. Defaults to false.

When enabled globally, you can use wrapCode=false in the code block meta to disable wrapping for a specific block. Conversely, when disabled globally, you can use wrapCode or wrapCode=true to enable wrapping for a specific block. See Wrap code for details.

#markdown.crossCompilerCache

• Type: boolean
• Default: true

Whether to enable cross-compiler cache for MDX compilation during rspress build. When enabled, Rspress will cache MDX parsing results across multiple compilers (web and node), which can speed up the production build process by approximately 10%.

This option only takes effect in production builds and is inspired by Docusaurus.

import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    crossCompilerCache: true,
  },
});

#markdown.globalComponents

• Type: string[]

Register component to the global scope, which will make it automatically available in every MDX file, without any import statements.For example:

import { defineConfig } from '@rspress/core';
import path from 'path';

export default defineConfig({
  markdown: {
    globalComponents: [path.join(__dirname, 'src/src/components/Alert.tsx')],
  },
});

Then you can use the Alert component in any MDX file:

<Alert type="info">This is a info alert</Alert>

#markdown.extractDescription

• Type: boolean
• Default: true

Whether to extract the description from the content. If enabled, Rspress will automatically extract the first paragraph before the h2 heading as the description of the page.

#markdown.cjkFriendlyEmphasis

• Type: boolean
• Default: true

Whether to enable CJK-friendly emphasis and strikethrough parsing. When enabled, **, *, and ~~ will correctly parse as emphasis/strikethrough when CJK characters are adjacent to the outside of the markers, even if punctuation (CJK or ASCII) appears inside the markers.

This addresses a CommonMark spec limitation where emphasis markers are not recognized correctly when CJK characters are adjacent. For example, **该星号不会被识别，而是直接显示。**这是因为它没有被识别为强调符号。 would not render the first sentence as bold without this option, because CJK characters follow the closing **. For more details on this extension, see markdown-cjk-friendly.

Enabled by default. To disable:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    cjkFriendlyEmphasis: false,
  },
});