作者：Titus Wormer
扩展 MDX
本文解释了如何扩展 MDX 内容——具体来说，如何用插件来转换内容。 有关如何传递组件、props 和布局，请参见§ 使用 MDX。 有关如何将 MDX 集成到你的项目中，请参见§ 快速开始。
目录
组件与插件
使用 @mdx-js/mdx 或其集成时有三个扩展点：
- 传递给编译器的选项（参见¶
@mdx-js/mdx中的 API） - 钩入编译多个阶段的插件（参见 remark 插件、rehype 插件 和 recma 插件）
- 在运行时传递、定义或导入的组件（参见§ 使用 MDX）
大多数时候，这些组件和插件不与 MDX 耦合。 例如，如果你使用 React，你可以在 MDX 中使用 <ReactConfetti />。 或者，你可以使用插件 remark-gfm 在 MDX 中开启 GFM 特性。 有时，我们需要特定的组件或特定的插件来与 MDX 配合使用。 我们在此页面上汇总了这些内容。
组件列表
注意：有其他专门与 MDX 配合使用的组件？ 请提交 PR 添加到这里！
插件列表
MDX 专用 remark 插件
remark-directive-mdx— 将 Markdown 指令（:directive[]）转换为 JSX 元素remark-mdx-chartjs— 使用react-chartjs-2替换围栏代码块为图表。remark-mdx-frontmatter— 将 frontmatter（YAML）元数据转换为导出remark-mdx-math-enhanced— 用其中的 JavaScript 增强数学公式remark-mdx-remove-esm— 移除 import 和/或 export 语句（mdxjsEsm）remark-mdx-remove-expressions— 移除 MDX 内容中花括号 内的 MDX 表达式
另见 remark 插件列表。
MDX 专用 rehype 插件
rehype-mdx-code-props— 将代码meta字段解释为 JSX propsrehype-mdx-import-media— 将媒体源更改为 JavaScript 导入rehype-mdx-title— 将页面标题暴露为字符串rehype-mdx-toc— 将目录数据导出到 MDX 模块中
另见 rehype 插件列表。
MDX 专用 recma 插件
recma-export-filepath— 导出文件路径recma-mdx-change-props— 将_createMdxContent函数中的参数更改为_propsrecma-mdx-displayname— 为MDXContent组件添加displayName，以便在生产环境中 切换它们recma-mdx-escape-missing-components— 为缺失的组件设置() => null的默认值，而不是 抛出错误recma-mdx-is-mdx-component— 在 MDX 组件上添加isMdxComponent字段recma-nextjs-static-props— 生成getStaticProps在 Next.js 中暴露顶层标识符recma-module-to-function— 将模块转换为函数体
另见 recma 插件列表。
注意：有其他专门与 MDX 配合使用的 unified 插件？ 请提交 PR 添加到这里！
使用插件
在哪里传递插件编码在它们的名称中： remark 插件放在 remarkPlugins 中， rehype 插件放在 rehypePlugins 中， recma 插件放在 ProcessorOptions 的 recmaPlugins 中。 这些字段接受插件和/或 [plugin, options] 的列表：
import {compile} from '@mdx-js/mdx'
import rehypeKatex from 'rehype-katex' // Render math with KaTeX.
import remarkFrontmatter from 'remark-frontmatter' // YAML and such.
import remarkGfm from 'remark-gfm' // Tables, footnotes, strikethrough, task lists, literal URLs.
import remarkMath from 'remark-math' // Support math like `$so$`.
const file = '# hi'
// One plugin:
await compile(file, {remarkPlugins: [remarkGfm]})
// A plugin with options:
await compile(file, {remarkPlugins: [[remarkFrontmatter, 'toml']]})
// Two plugins:
await compile(file, {remarkPlugins: [remarkGfm, remarkFrontmatter]})
// Two plugins, first w/ options:
await compile(file, {remarkPlugins: [[remarkGfm, {singleTilde: false}], remarkFrontmatter]})
// remark and rehype plugins:
await compile(file, {rehypePlugins: [rehypeKatex], remarkPlugins: [remarkMath]})
// remark and rehype plugins, last w/ options:
await compile(file, {
// A plugin with options:
rehypePlugins: [[rehypeKatex, {strict: true, throwOnError: true}]],
remarkPlugins: [remarkMath]
})
(alias) function compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compileCompile MDX to JS.
- @param vfileCompatible MDX document to parse.
- @param compileOptions Compile configuration (optional).
- @return Promise to compiled file.
(alias) function rehypeKatex(options?: Readonly<Options> | null | undefined): (tree: Root, file: VFile) => undefined
import rehypeKatexRender elements with a language-math (or math-display, math-inline) class with KaTeX.
- @param options Configuration (optional).
- @returns Transform.
(alias) function remarkFrontmatter(options?: Options | null | undefined): undefined
import remarkFrontmatterAdd support for frontmatter.
Notes
Doesn’t parse the data inside them: create your own plugin to do that.
- @param options Configuration (default:
'yaml'). - @returns Nothing.
(alias) function remarkGfm(options?: Options | null | undefined): undefined
import remarkGfmAdd support GFM (autolink literals, footnotes, strikethrough, tables, tasklists).
- @param options Configuration (optional).
- @returns Nothing.
(alias) function remarkMath(options?: Readonly<Options> | null | undefined): undefined
import remarkMathAdd support for math.
- @param options Configuration (optional).
- @returns Nothing.
const file: "# hi"(alias) compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compileCompile MDX to JS.
- @param vfileCompatible MDX document to parse.
- @param compileOptions Compile configuration (optional).
- @return Promise to compiled file.
const file: "# hi"(property) remarkPlugins?: PluggableList | null | undefinedList of remark plugins (optional).
(alias) function remarkGfm(options?: Options | null | undefined): undefined
import remarkGfmAdd support GFM (autolink literals, footnotes, strikethrough, tables, tasklists).
- @param options Configuration (optional).
- @returns Nothing.
(alias) compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compileCompile MDX to JS.
- @param vfileCompatible MDX document to parse.
- @param compileOptions Compile configuration (optional).
- @return Promise to compiled file.
const file: "# hi"(property) remarkPlugins?: PluggableList | null | undefinedList of remark plugins (optional).
(alias) function remarkFrontmatter(options?: Options | null | undefined): undefined
import remarkFrontmatterAdd support for frontmatter.
Notes
Doesn’t parse the data inside them: create your own plugin to do that.
- @param options Configuration (default:
'yaml'). - @returns Nothing.
(alias) compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compileCompile MDX to JS.
- @param vfileCompatible MDX document to parse.
- @param compileOptions Compile configuration (optional).
- @return Promise to compiled file.
const file: "# hi"(property) remarkPlugins?: PluggableList | null | undefinedList of remark plugins (optional).
(alias) function remarkGfm(options?: Options | null | undefined): undefined
import remarkGfmAdd support GFM (autolink literals, footnotes, strikethrough, tables, tasklists).
- @param options Configuration (optional).
- @returns Nothing.
(alias) function remarkFrontmatter(options?: Options | null | undefined): undefined
import remarkFrontmatterAdd support for frontmatter.
Notes
Doesn’t parse the data inside them: create your own plugin to do that.
- @param options Configuration (default:
'yaml'). - @returns Nothing.
(alias) compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compileCompile MDX to JS.
- @param vfileCompatible MDX document to parse.
- @param compileOptions Compile configuration (optional).
- @return Promise to compiled file.
const file: "# hi"(property) remarkPlugins?: PluggableList | null | undefinedList of remark plugins (optional).
(alias) function remarkGfm(options?: Options | null | undefined): undefined
import remarkGfmAdd support GFM (autolink literals, footnotes, strikethrough, tables, tasklists).
- @param options Configuration (optional).
- @returns Nothing.
(property) singleTilde: boolean(alias) function remarkFrontmatter(options?: Options | null | undefined): undefined
import remarkFrontmatterAdd support for frontmatter.
Notes
Doesn’t parse the data inside them: create your own plugin to do that.
- @param options Configuration (default:
'yaml'). - @returns Nothing.
(alias) compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compileCompile MDX to JS.
- @param vfileCompatible MDX document to parse.
- @param compileOptions Compile configuration (optional).
- @return Promise to compiled file.
const file: "# hi"(property) rehypePlugins?: PluggableList | null | undefinedList of rehype plugins (optional).
(alias) function rehypeKatex(options?: Readonly<Options> | null | undefined): (tree: Root, file: VFile) => undefined
import rehypeKatexRender elements with a language-math (or math-display, math-inline) class with KaTeX.
- @param options Configuration (optional).
- @returns Transform.
(property) remarkPlugins?: PluggableList | null | undefinedList of remark plugins (optional).
(alias) function remarkMath(options?: Readonly<Options> | null | undefined): undefined
import remarkMathAdd support for math.
- @param options Configuration (optional).
- @returns Nothing.
(alias) compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compileCompile MDX to JS.
- @param vfileCompatible MDX document to parse.
- @param compileOptions Compile configuration (optional).
- @return Promise to compiled file.
const file: "# hi"(property) rehypePlugins?: PluggableList | null | undefinedList of rehype plugins (optional).
(alias) function rehypeKatex(options?: Readonly<Options> | null | undefined): (tree: Root, file: VFile) => undefined
import rehypeKatexRender elements with a language-math (or math-display, math-inline) class with KaTeX.
- @param options Configuration (optional).
- @returns Transform.
(property) strict: boolean(property) throwOnError: boolean(property) remarkPlugins?: PluggableList | null | undefinedList of remark plugins (optional).
(alias) function remarkMath(options?: Readonly<Options> | null | undefined): undefined
import remarkMathAdd support for math.
- @param options Configuration (optional).
- @returns Nothing.
创建插件
为 MDX 创建插件与为 remark、rehype 或 recma 创建插件基本相同。 在 § unifiedjs.com 上的学习中有几个指南和教程。
对于插件的 MDX 特定部分，建议阅读 ¶ 架构 了解 @mdx-js/mdx 的工作原理。 有关表示 MDX 特定特性的节点类型信息，请参见 ¶ remark-mdx 中的语法树 并使用我们交互式的 § Playground。