MDX 插件

提供 MDX 支持。

什么是 MDX

MDX 让你可以在 markdown 内容中使用 JSX。你可以导入组件,例如图表或 alert,并将其嵌入到你的内容中。这使得使用组件编写长篇内容变得轻松有趣。

快速开始

安装插件

你可以通过如下的命令安装插件:

npm
yarn
pnpm
bun
npm add @rsbuild/plugin-mdx -D

注册插件

你可以在 rsbuild.config.ts 文件中注册插件:

rsbuild.config.ts
import { pluginMdx } from '@rsbuild/plugin-mdx';

export default {
  plugins: [pluginMdx()],
};

注册插件后,你可以在代码中引入 .mdx.md 文件作为组件使用。

类型声明

在 TypeScript 项目中,你需要为 .mdx 文件添加类型定义,使 TypeScript 能够正确识别它。

请在 src 目录下创建 env.d.ts,并添加以下内容:

src/env.d.ts
declare module '*.md' {
  let MDXComponent: () => JSX.Element;
  export default MDXComponent;
}
declare module '*.mdx' {
  let MDXComponent: () => JSX.Element;
  export default MDXComponent;
}

选项

如果你需要自定义 MDX 的编译行为,可以使用以下配置项。

mdxLoaderOptions

传递给 @mdx-js/loader 的选项,请查阅 @mdx-js/loader 文档 来了解具体用法。

  • 类型: MdxLoaderOptions
  • 默认值: {}
  • 示例:
pluginMdx({
  mdxLoaderOptions: {
    // 使用 Vue JSX
    jsxImportSource: 'vue',
  },
});

extensions

指定使用 MDX loader 编译的文件后缀,默认包括 .md 文件和 .mdx 文件。

  • 类型: string[]
  • 默认值: ['.mdx', '.md']

比如仅编译 .mdx 文件,可以设置为:

pluginMdx({
  extensions: ['.mdx'],
});