close
Rspress
指南
插件
API
版本
指南
插件
API
简体中文

构建配置

builderConfig

  • 类型: RsbuildConfig

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

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 丰富的插件生态来增强和扩展构建能力。

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

export default defineConfig({
  builderConfig: {
    plugins: [pluginVue()],
  },
});
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',
      }),
    ],
  },
});
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.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.showLineNumbers

  • 类型: boolean

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

markdown.defaultWrapCode

  • 类型: boolean

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

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>