skip to content
rainbow ゆめこ

Rspress全局组件

/ 3 min read

在 Rspress 中,你可以在 MDX 文件中注册全局可用的组件,主要通过 markdown.globalComponents 配置实现。这与之前讨论的 globalUIComponents 不同,后者是在整个站点层面注册组件,而 markdown.globalComponents 专门用于在 MDX 文件中注册全局可用的组件。

在配置文件中注册 MDX 全局组件

你可以在 rspress.config.ts 中通过 markdown.globalComponents 配置项注册全局可用的 MDX 组件:

import { defineConfig } from 'rspress/config';
import path from 'path';
export default defineConfig({
markdown: {
globalComponents: [path.join(__dirname, 'src/src/components/Alert.tsx')],
},
});

config-build.mdx:225-233

注册后,你可以在任何 MDX 文件中直接使用这些组件,而无需导入:

<Alert type="info">This is a info alert</Alert>

config-build.mdx:238-240

通过插件注册 MDX 全局组件

你也可以通过插件系统注册 MDX 全局组件:

import { RspressPlugin } from '@rspress/shared';
export function pluginForDoc(): RspressPlugin {
return {
name: 'plugin-name',
markdown: {
mdxRs: false,
globalComponents: [
// 为 MDX 注册全局组件
],
},
};
}

plugin-api.mdx:218-236

重要注意事项

使用 markdown.globalComponents 时,必须将 markdown.mdxRs 设置为 false,否则全局组件将不会生效:

export default defineConfig({
markdown: {
mdxRs: false,
globalComponents: [path.join(__dirname, 'src/src/components/Alert.tsx')],
},
});

config-build.mdx:242-244

这是因为 Rspress 默认使用基于 Rust 的 MDX 编译器(mdxRs),但全局组件功能需要使用 JavaScript 版本的编译器才能正常工作。

与 globalUIComponents 的区别

  • markdown.globalComponents:仅在 MDX 文件内部可用,需要禁用 Rust 版本的 MDX 编译器
  • globalUIComponents:在整个站点层面注册组件,不受 MDX 编译器版本的影响

组件实现示例

你的全局 MDX 组件是普通的 React 组件,例如:

import React from 'react';
const Alert = ({ type, children }) => {
return (
<div className={`alert alert-${type}`}>
{children}
</div>
);
};
export default Alert;

注册后,这个组件可以在任何 MDX 文件中直接使用,无需导入。

Notes

在 Rspress 中注册 MDX 全局组件需要使用 markdown.globalComponents 配置,并且必须将 markdown.mdxRs 设置为 false。这与 globalUIComponents 不同,后者是在整个站点层面注册组件,而前者专门用于在 MDX 文件内部使用的组件。