构建配置

builderConfig

类型: RsbuildConfig

用于自定义 Rsbuild 的配置项，完整配置项请查看 Rsbuild - 配置。

示例：使用 resolve.alias 配置路径别名：

rspress.config.ts

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

示例：使用 tools.rspack 修改 Rspack 配置，比如注册一个 webpack 或 Rspack 插件。比如：

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

如果你想要修改产物输出目录，请使用 outDir。

builderConfig.plugins

类型: RsbuildPlugin[]

用于注册 Rsbuild 插件。

你可以利用 Rsbuild 丰富的插件生态来增强和扩展构建能力。

示例：通过 @rsbuild/plugin-vue 支持 Vue SFC。

rspress.config.ts

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

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

示例：通过 rsbuild-plugin-google-analytics 添加 Google analytics。

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

示例：通过 rsbuild-plugin-open-graph 添加 Open Graph meta 标签。

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

你也可以覆盖内置的 @rsbuild/plugin-react 并自定义插件的选项。

比如：

rspress.config.ts

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

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

默认配置

如果你需要查看默认的 Rspack 或 Rsbuild 配置，可以在执行 rspress dev 或 rspress build 命令时，添加 DEBUG=rsbuild 参数：

DEBUG=rsbuild rspress dev

在执行后，doc_build 目录下会生成 rsbuild.config.js 文件，里面包含了完整的 builderConfig。

请查看 Rsbuild - 调试模式来了解更多调试 Rsbuild 的方法。

markdown

配置 MDX 相关的编译能力。

markdown.remarkPlugins

类型: Array
默认值: []

用于增加一些自定义 remark 插件。比如：

rspress.config.ts

import { defineConfig } from '@rspress/core';
import remarkAutolinkHeadings from 'remark-autolink-headings';

export default defineConfig({
  markdown: {
    remarkPlugins: [
      [
        remarkAutolinkHeadings,
        {
          behavior: 'wrap',
        },
      ],
    ],
  },
});

markdown.rehypePlugins

类型: Array

用于增加一些自定义的 rehype 插件。比如：

rspress.config.ts

import { defineConfig } from '@rspress/core';
import rehypeAutoLinkHeadings from 'rehype-autolink-headings';

export default defineConfig({
  markdown: {
    rehypePlugins: [
      [
        rehypeAutoLinkHeadings,
        {
          behavior: 'wrap',
        },
      ],
    ],
  },
});

markdown.shiki

类型: import('@shikijs/rehype').RehypeShikiOptions
默认值:

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

配置 Shiki 相关配置。具体可见 RehypeShikiOptions。

markdown.link

类型:

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

默认值: { checkDeadLinks: true, autoPrefix: true }

配置链接相关的配置。

markdown.link.checkDeadLinks

类型: boolean | { excludes: string[] | ((url: string) => boolean) }
默认值: true

开启这个配置后，会基于约定式路由对文档中的链接进行检查，若出现无法访问的链接，构建会抛出错误并退出。

如果存在误判链接的情况，可以通过 excludes 配置忽略该错误：

rspress.config.ts

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

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

markdown.link.autoPrefix

类型: boolean
默认值: true

开启这个配置后，会基于约定式路由对文档中的链接自动增加关于国际化和多版本前缀。

比如，用户在 docs/zh/guide/index.md 中写了一个链接 [](/guide/getting-started)，Rspress 会自动将其转换为 [](/zh/guide/getting-started)。

markdown.image

类型:

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

默认值: { checkDeadImages: true }

配置图片相关选项。

markdown.image.checkDeadImages

类型: boolean | { excludes: string[] | ((url: string) => boolean) }
默认值: true

开启该配置后，Rspress 会检查文档中的本地图片。如果图片引用了不存在的文件，构建会抛出错误并退出。

对于相对图片路径（例如 ./image.png），Rspress 会相对于当前文档解析文件；对于绝对图片路径（例如 /image.png），Rspress 会从 public 目录下解析文件。

如果某些图片被误判，可以通过 excludes 配置忽略这些错误：

rspress.config.ts

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

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

markdown.showLineNumbers

类型: boolean

是否显示代码块的行号。默认为 false。

全局启用后，可以在代码块 meta 中使用 lineNumbers=false 来为特定代码块禁用行号。反之，全局未启用时，可以使用 lineNumbers 或 lineNumbers=true 来为特定代码块启用行号。详见显示代码行号。

markdown.defaultWrapCode

类型: boolean

是否默认启用长代码换行展示。默认为 false。

全局启用后，可以在代码块 meta 中使用 wrapCode=false 来为特定代码块禁用换行。反之，全局未启用时，可以使用 wrapCode 或 wrapCode=true 来为特定代码块启用换行。详见代码换行。

markdown.defaultCodeOverflow

类型: { height?: number; behavior?: 'fold' | 'scroll' }

默认情况下，Rspress 的代码块会完全展开显示，没有 overflow 行为。你可以通过 ```tsx fold 等 meta 属性控制单个代码块的 overflow 行为。此配置项可以为所有代码块设置全局默认的 overflow 行为，超过指定高度时自动应用。

height：高度阈值，单位为像素。未设置时不应用任何 overflow 行为。
behavior：超出高度时的处理方式，默认为 'scroll'。
- 'scroll'：固定高度，显示垂直滚动条。
- 'fold'：可折叠，显示展开/收起按钮。

rspress.config.ts

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

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

单个代码块可通过 height 或 fold meta 属性覆盖默认行为。详见代码块高度。

markdown.crossCompilerCache

类型: boolean
默认值: true

是否在 rspress build 时启用跨编译器缓存。启用后，Rspress 会在多个编译器（web 和 node）之间缓存 MDX 解析结果，从而加速生产环境构建，构建时间可减少约 10%。

该选项仅在生产环境构建时生效，灵感来自 Docusaurus。

rspress.config.ts

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

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

markdown.globalComponents

类型: string[]

注册全局组件，无需 import 语句，就可以在每个 MDX 文件中使用。比如：

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

这样你就可以在 MDX 文件中使用 Alert 组件了：

test.mdx

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

markdown.extractDescription

类型: boolean
默认值: true

是否自动从 Markdown 内容中提取描述。启用后，Rspress 会提取 h1 标题下方第一段有内容的段落作为页面描述。如果在 frontmatter 中指定了 description，则优先使用，跳过自动提取。

提取的描述用于 <meta name="description"> 和 Open Graph 的 <meta property="og:description"> 标签。详情请参阅自定义 Head 标签 - description 的获取方式。

markdown.cjkFriendlyEmphasis

类型: boolean
默认值: true

是否启用对 CJK（中日韩）友好的强调和删除线解析。启用后，即使标记内部含有标点符号（CJK 或 ASCII），只要标记外侧紧邻 CJK 字符，**、* 和 ~~ 也能正确解析为强调或删除线。

此选项解决了 CommonMark 规范的一个限制，该限制导致强调标记在 CJK 字符相邻时无法正常工作。例如，未启用此选项时 **该星号不会被识别，而是直接显示。**这是因为它没有被识别为强调符号。 中的第一句不会被渲染为粗体，因为闭合 ** 后紧跟着 CJK 字符。有关此扩展的更多详情，请参见 markdown-cjk-friendly。

默认启用。如需禁用：

rspress.config.ts

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

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

#构建配置

#builderConfig

#builderConfig.plugins

#默认配置

#markdown

#markdown.remarkPlugins

#markdown.rehypePlugins

#markdown.shiki

#markdown.link

#markdown.link.checkDeadLinks

#markdown.link.autoPrefix

#markdown.image

#markdown.image.checkDeadImages

#markdown.showLineNumbers

#markdown.defaultWrapCode

#markdown.defaultCodeOverflow

#markdown.crossCompilerCache

#markdown.globalComponents

#markdown.extractDescription

#markdown.cjkFriendlyEmphasis

构建配置

builderConfig

builderConfig.plugins

默认配置

markdown

markdown.remarkPlugins

markdown.rehypePlugins

markdown.shiki

markdown.link

markdown.link.checkDeadLinks

markdown.link.autoPrefix

markdown.image

markdown.image.checkDeadImages

markdown.showLineNumbers

markdown.defaultWrapCode

markdown.defaultCodeOverflow

markdown.crossCompilerCache

markdown.globalComponents

markdown.extractDescription

markdown.cjkFriendlyEmphasis