#Build config

#builderConfig

• Type: RsbuildConfig

Customizes the Rsbuild configuration. For details, see 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 SFCs with @rsbuild/plugin-vue

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

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

• Example: Add Google Analytics with 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 with 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

To inspect the default Rspack or Rsbuild config, set DEBUG=rsbuild when running rspress dev or rspress build:

DEBUG=rsbuild rspress dev

After the command runs, Rspress creates rsbuild.config.js in the doc_build directory. The file contains the complete builderConfig.

See Rsbuild - Debug Mode for more information about debugging Rsbuild.

#markdown

Configures MDX compilation.

#markdown.remarkPlugins

• Type: Array
• Default: []

Configures remark plugins. For example:

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

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

#markdown.rehypePlugins

• Type: Array

Configures rehype plugins. 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) };
  checkAnchors?: boolean | { excludes: string[] | ((url: string) => boolean) };
  autoPrefix?: boolean;
};

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

Configure link-related options.

#markdown.link.checkDeadLinks

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

When enabled, Rspress checks document links against the conventional routes. If a link is not accessible, the build fails.

If a link is reported incorrectly, ignore it with excludes:

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

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

#markdown.link.checkAnchors

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

After enabling this configuration, Rspress will check whether internal link anchors exist in the target Markdown or MDX page. It checks same-page anchors, relative links, and absolute links, but skips external URL anchors.

If an anchor is reported incorrectly, ignore it with excludes:

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

export default defineConfig({
  markdown: {
    link: {
      checkAnchors: {
        excludes: ['/guide/getting-started#custom-anchor'],
      },
    },
  },
});

#markdown.link.autoPrefix

• Type: boolean
• Default: true

When enabled, Rspress automatically adds link prefixes based on the conventional routes for i18n and multi-version docs.

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

• Type:

export type RemarkImageOptions = {
  checkDeadImages?:
    boolean | { excludes: string[] | ((url: string) => boolean) };
};

• Default: { checkDeadImages: true }

Configure image-related options.

#markdown.image.checkDeadImages

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

When enabled, Rspress checks local images in documents. If an image references a file that does not exist, the build fails.

For relative image paths (e.g., ./image.png), the file is resolved relative to the current document. For absolute image paths (e.g., /image.png), the file is resolved from the public directory.

If an image is reported incorrectly, ignore it with excludes:

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

export default defineConfig({
  markdown: {
    image: {
      checkDeadImages: {
        excludes: ['/generated-diagram.png'],
      },
    },
  },
});

#markdown.showLineNumbers

• Type: boolean

Controls whether code blocks show line numbers. 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

Controls whether long code lines wrap 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.defaultCodeOverflow

• Type: { height?: number; behavior?: 'fold' | 'scroll' }

By default, Rspress code blocks are fully expanded with no overflow behavior. You can use meta attributes like ```tsx fold to control overflow for individual code blocks. This config sets the global default overflow behavior, which is automatically applied when code blocks exceed the specified height.

• height: Height threshold in pixels. When not set, no overflow behavior is applied.
• behavior: How to handle code blocks exceeding the height. Defaults to 'scroll'.
  • 'scroll': Fixed height with vertical scrollbar.
  • 'fold': Collapsible with an expand/collapse button.

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

export default defineConfig({
  markdown: {
    defaultCodeOverflow: {
      height: 400,
      behavior: 'fold',
    },
  },
});

Individual code blocks can override the default using height or fold meta attributes. See Code block height 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[]

Registers components globally so they are available in every MDX file without 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 an info alert</Alert>

#markdown.extractDescription

• Type: boolean
• Default: true

Whether to automatically extract the description from the markdown content. When enabled, Rspress extracts the first contentful paragraph below the h1 heading as the page description. If description is specified in frontmatter, it takes priority and automatic extraction is skipped.

The extracted description is used for <meta name="description"> and Open Graph <meta property="og:description"> tags. See Custom Head - How description is determined for details.

#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,
  },
});