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

构建配置

builderConfig

  • Type: RsbuildConfig

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

rspress.config.ts
export default defineConfig({
  builderConfig: {
    source: {
      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。

builderPlugins

  • Type: RsbuildPlugin[]

用于注册 Rsbuild 插件。

你可以在 Rspress 项目中使用 Rsbuild 丰富的插件，来快速扩展构建能力。

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

export default defineConfig({
  builderPlugins: [pluginVue()],
});
rspress.config.ts
import { defineConfig } from 'rspress/config';
import { pluginGoogleAnalytics } from 'rsbuild-plugin-google-analytics';

export default defineConfig({
  builderPlugins: [
    pluginGoogleAnalytics({
      // replace this with your Google tag ID
      id: 'G-xxxxxxxxxx',
    }),
  ],
});
rspress.config.ts
import { defineConfig } from 'rspress/config';
import { pluginOpenGraph } from 'rsbuild-plugin-open-graph';

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

你也可以覆盖内置的 @rsbuild/plugin-react、@rsbuild/plugin-sass 和 @rsbuild/plugin-less 插件，并传入相关插件选项。

rspress.config.ts
import { defineConfig } from 'rspress/config';
import { pluginLess } from '@rsbuild/plugin-less';

export default defineConfig({
  builderPlugins: [
    pluginLess({
      lessLoaderOptions: {
        lessOptions: {
          math: 'always',
        },
      },
    }),
  ],
});

默认配置

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

DEBUG=rsbuild rspress dev

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

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

markdown

  • Type: Object

配置 MDX 相关的编译能力。

markdown.remarkPlugins

  • Type: Array
  • Default: []

配置 remark 插件。比如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

markdown.rehypePlugins

  • Type: Array

配置 rehype 插件。比如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

markdown.checkDeadLinks

  • Type: boolean
  • Default: false

是否检查死链。比如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

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

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

markdown.mdxRs

  • Type: boolean | { include: (filepath: string) => boolean }

  • Default: true

是否使用 MDX 的 Rust 版本编译器，默认开启。比如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  markdown: {
    // 使用 JS 版本的 MDX 编译器
    mdxRs: false,
  },
});

你也可以提供函数来决定哪些文件使用 MDX 的 Rust 版本编译器。比如：

rspress.config.ts
import { defineConfig } from 'rspress/config';

export default defineConfig({
  markdown: {
    mdxRs: {
      include: (filepath: string) => filepath.includes('foo.mdx'),
    },
  },
});
注意

mdxRs 能力底层基于 Rspress 自研的 @rspress/mdx-rs 库来实现，性能比 JS 版本的 MDX 编译器提升 10 倍以上，但不支持 JS 的插件。

markdown.showLineNumbers

  • Type: boolean

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

markdown.defaultWrapCode

  • Type: boolean

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

markdown.globalComponents

  • Type: string[]

注册全局组件，无需通过导入声明，就可以在每个 MDX 文件中使用。比如：

rspress.config.ts
import { defineConfig } from 'rspress/config';
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>
警告

请在配置 globalComponents 时设置 markdown.mdxRs 为 false 以开启 JS 版本的编译器，否则会导致全局组件不生效。

markdown.highlightLanguages

  • Type: [string, string][]
  • Default:
const DEFAULT_HIGHLIGHT_LANGUAGES = [
  ['js', 'javascript'],
  ['ts', 'typescript'],
  ['jsx', 'tsx'],
  ['xml', 'xml-doc'],
  ['md', 'markdown'],
  ['mdx', 'tsx'],
];

Rspress 支持自动导入高亮的语言，并默认做了一些语言别名。

  • 默认基于 Prism.js 实现，你也可以通过 @rspress/plugin-shiki 切换到 Shiki。
  • 默认配置别名的语言包括 js、jsx、ts、tsx、xml、md、mdx。

你也可以在这些默认别名的基础上进行扩展，比如：

rspress.config.ts
import { defineConfig } from 'rspress/config';
import path from 'path';

export default defineConfig({
  markdown: {
    highlightLanguages: [
      // 别名为 md, 全名为 markdown
      ['md', 'markdown'],
    ],
  },
});

每项语言的别名以 [string, string] 格式配置，前者为语言的别名，后者为语言的全名，你可以前往文件列表查看所有支持的语言全名。