> For AI agents: the complete documentation index is available at https://rspress.rs/llms.txt, the full documentation bundle is available at https://rspress.rs/llms-full.txt.

# Build config

## builderConfig

- **Type**: `RsbuildConfig`

Customizes the Rsbuild configuration. For details, see [Rsbuild - Config](https://rsbuild.rs/config/).

- Example: Use [resolve.alias](https://rsbuild.rs/config/resolve/alias) to configure path aliases:

```ts title="rspress.config.ts"
export default defineConfig({
  builderConfig: {
    resolve: {
      alias: {
        '@common': './src/common',
      },
    },
  },
});
```

- Example: Use [tools.rspack](https://rsbuild.rs/config/tools/rspack) to modify the Rspack configuration, such as registering a webpack or Rspack plugin:

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

::: warning

To modify the output directory, use [outDir](https://rspress.rs/api/config/config-basic.md#outdir).

:::

## builderConfig.plugins

- **Type**: `RsbuildPlugin[]`

To register [Rsbuild plugins](https://rsbuild.rs/plugins/list/).

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

- Example: Support Vue SFCs with [@rsbuild/plugin-vue](https://rsbuild.rs/plugins/list/plugin-vue)

```ts title="rspress.config.ts"
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](https://github.com/rstackjs/rsbuild-plugin-google-analytics).

```ts title="rspress.config.ts"
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](https://github.com/rstackjs/rsbuild-plugin-open-graph).

```ts title="rspress.config.ts"
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](https://rsbuild.rs/plugins/list/plugin-react) and customize the plugin options.

For example:

```ts title="rspress.config.ts"
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`:

```bash
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](https://rsbuild.rs/guide/debug/debug-mode) for more information about debugging Rsbuild.

## markdown

Configures MDX compilation.

### markdown.remarkPlugins

- **Type**: `Array`
- **Default**: `[]`

Configures remark plugins. For example:

```ts title="rspress.config.ts"
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:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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

### markdown.shiki

- **Type**: `import('@shikijs/rehype').RehypeShikiOptions`

- **Default**:

```ts
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](https://github.com/shikijs/shiki/blob/main/packages/rehype/src/types.ts).

### markdown.link

- **Type**:

```ts
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`:

```ts title="rspress.config.ts"
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`

:::info
`checkAnchors` is currently disabled by default. It will be enabled by default in a future version.
:::

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`:

```ts title="rspress.config.ts"
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](https://rspress.rs/guide/basic/i18n.md) and [multi-version docs](https://rspress.rs/guide/basic/multi-version.md).

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**:

```ts
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`:

```ts title="rspress.config.ts"
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](https://rspress.rs/guide/use-mdx/code-blocks.md#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](https://rspress.rs/guide/use-mdx/code-blocks.md#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.

```ts title="rspress.config.ts"
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](https://rspress.rs/guide/use-mdx/code-blocks.md#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](https://docusaurus.io/).

```ts title="rspress.config.ts"
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:

```ts title="rspress.config.ts"
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:

```mdx title="test.mdx"
<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](https://rspress.rs/api/config/config-frontmatter.md#description), 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](https://rspress.rs/guide/advanced/custom-head.md#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](https://github.com/commonmark/commonmark-spec/issues/650) 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](https://github.com/tats-u/markdown-cjk-friendly).

Enabled by default. To disable:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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