构建配置

builderConfig

  • Type: RsbuildConfig

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

比如,将产物目录修改为 doc_dist

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

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

默认配置

如果你需要查看默认的 Rspack 或 Rsbuild 配置,可以在执行 rspress devrspress 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',
        },
      ],
    ],
  },
});
  • 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.mdxRsfalse 以开启 JS 版本的编译器,否则会导致全局组件不生效。

markdown.highlightLanguages

  • Type: (string | [string, string])[]
  • Default:
const DEFAULT_HIGHLIGHT_LANGUAGES = [
  ['js', 'javascript'],
  ['ts', 'typescript'],
  ['jsx', 'tsx'],
  'tsx',
  'json',
  'css',
  'scss',
  'less',
  ['xml', 'xml-doc'],
  'diff',
  'yaml',
  ['md', 'markdown'],
  ['mdx', 'tsx'],
  'bash',
];

注册需要代码高亮的语言。

  • 默认基于 Prism.js 实现,你也可以通过 @rspress/plugin-shiki 切换到 Shiki。
  • 默认支持的语言包括 jsjsxtstsxjsoncssscsslesshtmlxmldiffyamlmdmdxbash

Rspress 默认没有注册所有可支持的语言,这是为了减少构建产物的包体积。你可以在这些默认语言的基础上进行扩展,比如:

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

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

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