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

构建配置

builderConfig

  • Type: Object

用于自定义 Modern.js Builder 的配置项，完整配置项请查看 Modern.js Builder - API。

比如，将产物目录修改为 doc_dist：

rspress.config.ts
export default defineConfig({
  builderConfig: {
    output: {
      distPath: {
        root: 'doc_dist',
      },
    },
  },
});

builderPlugins

  • Type: BuilderPlugin[]

用于加入 Modern.js Builder 的插件，比如：

rspress.config.ts
import { defineConfig } from 'rspress/config';
import { builderPluginStylus } from '@rspress/builder-plugin-stylus';

export default defineConfig({
  builderPlugins: [builderPluginStylus()],
});

默认配置

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

DEBUG=builder rspress dev

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

请查看 Modern.js Builder - 调试模式 来了解更多调试 Builder 的方法。

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

  • Type: boolean

是否使用 MDX 的 Rust 版本编译器，为实验性质功能。比如：

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

export default defineConfig({
  markdown: {
    experimentalMdxRs: true,
  },
});
注意

这个功能底层基于 Rspress 自研的 @rspress/mdx-rs 库来实现，性能比 JS 版本的 MDX 编译器提升 10 倍以上，但目前还不支持 JS 版本的插件，如果你需要加入自定义的 remark 或 rehype 插件，建议不要开启这个功能。

markdown.showLineNumbers

  • 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 时开启 experimentalMdxRs，否则会导致全局组件不生效。