构建配置
builderConfig
用于自定义 Rsbuild 的配置项，完整配置项请查看 Rsbuild - 配置。
比如，将产物目录修改为 doc_dist：
rspress.config.ts
export default defineConfig({
builderConfig: {
output: {
distPath: {
root: 'doc_dist',
},
},
},
});
builderPlugins
用于注册 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
配置 MDX 相关的编译能力。
配置 remark 插件。比如：
rspress.config.ts
import { defineConfig } from 'rspress/config';
export default defineConfig({
markdown: {
remarkPlugins: [
[
require('remark-autolink-headings'),
{
behavior: 'wrap',
},
],
],
},
});
markdown.rehypePlugins
配置 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
是否使用 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
是否显示代码块的行号。默认为 false。
markdown.defaultWrapCode
是否默认启用长代码换行展示。默认为 false。
markdown.globalComponents
注册全局组件，无需通过导入声明，就可以在每个 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 支持自动导入高亮的语言，并默认做了一些语言别名。
你也可以在这些默认别名的基础上进行扩展，比如：
rspress.config.ts
import { defineConfig } from 'rspress/config';
import path from 'path';
export default defineConfig({
markdown: {
highlightLanguages: [
// 别名为 md, 全名为 markdown
['md', 'markdown'],
],
},
});
每项语言的别名以 [string, string] 格式配置，前者为语言的别名，后者为语言的全名，你可以前往文件列表查看所有支持的语言全名。
