Rspress全局组件

在 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 文件内部使用的组件。