扩展 MDX

¥Extending MDX

本文介绍如何扩展 MDX 内容，具体来说，如何使用插件转换内容。请参阅 § 使用 MDX 了解如何传递组件、属性和布局。请参阅 § 入门了解如何将 MDX 集成到你的项目中。

¥This article explains how to extend MDX content—specifically, how to transform content with plugins. See § Using MDX for how to pass components, props, and the layout. See § Getting started for how to integrate MDX into your project.

内容

¥Contents

组件和插件

¥Components & plugins

使用 @mdx-js/mdx 或其集成之一时，存在三个扩展点：

¥There are three extension points when using @mdx-js/mdx or one of its integrations:

传递给编译器的选项（参见 ¶ @mdx-js/mdx 中的 API）
¥Options passed to the compiler (see ¶ API in @mdx-js/mdx)
挂接到编译的几个阶段的插件（参见 remark 插件、rehype 插件和 recma 插件）
¥Plugins that hook into several stages of compilation (see remark plugins, rehype plugins, and recma plugins)
在运行时传递、定义或导入的组件（参见 § 使用 MDX）
¥Components passed, defined, or imported at runtime (see § Using MDX)

大多数时候，这些组件和插件不与 MDX 耦合。例如，如果你使用 React，那么你可以将 <ReactConfetti /> 与 MDX 结合使用。或者，你可以使用插件 remark-gfm 打开 MDX 中的 GFM 功能。有时，我们需要特定的组件或特定的插件来使用 MDX。我们正在此页面上整理这些内容。

¥Most of the time, these components and plugins are not coupled to MDX. For example, if you’re using React, then you can use <ReactConfetti /> with MDX. Or, you can use the plugin remark-gfm to turn on GFM features in MDX. Sometimes, we need specific components or specific plugins to work with MDX. We’re compiling those here on this page.

组件清单

¥List of components

PaulieScanlon/mdx-embed - 用于嵌入第 3 方内容的 React 组件，与 MDX 提供程序集成
¥PaulieScanlon/mdx-embed — React components for embedding 3rd party content, integrates w/ MDX provider
system-ui/theme-ui - 用于构建一致应用的 React 组件，与 MDX 提供程序集成
¥system-ui/theme-ui — React components for building consistent apps, integrates w/ MDX provider

注意：还有另一个专门与 MDX 配合使用的组件吗？请发送 PR 将其添加到此处！

¥Note: have another component that specifically works with MDX? Please send a PR to add it here!

插件列表

¥List of plugins

另请参阅 remark 插件列表、rehype 插件列表和 recma 插件列表。

remcohaszing/recma-export-filepath — 导出文件路径
¥remcohaszing/recma-export-filepath — export the filepath
ipikuka/recma-mdx-change-props — 将 _createMdxContent 函数中的参数更改为 _props
¥ipikuka/recma-mdx-change-props — changes the param as _props in the _createMdxContent function
domdomegg/recma-mdx-displayname — 添加 displayName 到 MDXContent 组件，以在生产中启用它们
¥domdomegg/recma-mdx-displayname — add a displayName to MDXContent components, to enable switching on them in production
ipikuka/recma-mdx-escape-missing-components — 为缺少的组件设置默认值 () => null，而不是抛出错误
¥ipikuka/recma-mdx-escape-missing-components — set a default value of () => null for missing components instead of throwing an error
remcohaszing/recma-mdx-is-mdx-component — 在 MDX 组件上添加 isMdxComponent 字段
¥remcohaszing/recma-mdx-is-mdx-component — add an isMdxComponent field on MDX components
remcohaszing/recma-nextjs-static-props — 生成 getStaticProps，在 Next.js 中公开顶层标识符
¥remcohaszing/recma-nextjs-static-props — generate getStaticProps exposing top level identifiers in Next.js
remcohaszing/rehype-mdx-code-props — 将代码 meta 字段解释为 JSX props
¥remcohaszing/rehype-mdx-code-props — interpret the code meta field as JSX props
remcohaszing/rehype-mdx-import-media — 将媒体源更改为 JavaScript 导入
¥remcohaszing/rehype-mdx-import-media — change media sources to JavaScript imports
remcohaszing/rehype-mdx-title — 将页面标题公开为字符串
¥remcohaszing/rehype-mdx-title — expose the page title as a string
pangelani/remark-mdx-chartjs — 使用 react-chartjs-2 将隔离代码块替换为图表。
¥pangelani/remark-mdx-chartjs — replace fenced code blocks with charts using react-chartjs-2.
remcohaszing/remark-mdx-frontmatter — 将 frontmatter (YAML) 元数据更改为导出
¥remcohaszing/remark-mdx-frontmatter — change frontmatter (YAML) metadata to exports
goodproblems/remark-mdx-math-enhanced — 使用 JavaScript 增强数学能力
¥goodproblems/remark-mdx-math-enhanced — enhance math with JavaScript inside it

注意：有另一个专门与 MDX 配合使用的统一插件吗？请发送 PR 将其添加到此处！

¥Note: have another unified plugin that specifically works with MDX? Please send a PR to add it here!

使用插件

¥Using plugins

插件名称中编码了传递插件的位置：remark 插件放在 remarkPlugins 中，rehype 插件放在 rehypePlugins 中，recma 插件放在 ProcessorOptions 的 recmaPlugins 中。这些字段需要插件和/或 [plugin, options] 的列表：

¥Where to pass plugins is encoded in their name: remark plugins go in remarkPlugins, rehype plugins go in rehypePlugins, and recma plugins go in recmaPlugins of ProcessorOptions. Those fields expect lists of plugins and/or of [plugin, options]:

TypeScript

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 compile

(alias) function rehypeKatex(options?: Readonly<Options> | null | undefined): (tree: Root, file: VFile) => undefined
import rehypeKatex

(alias) function remarkFrontmatter(options?: Options | null | undefined): undefined
import remarkFrontmatter

(alias) function remarkGfm(options?: Options | null | undefined): undefined
import remarkGfm

(alias) function remarkMath(options?: Readonly<Options> | null | undefined): undefined
import remarkMath

const file: "# hi"

(alias) compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

const file: "# hi"

(property) remarkPlugins?: PluggableList | null | undefined

(alias) function remarkGfm(options?: Options | null | undefined): undefined
import remarkGfm

(alias) compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

const file: "# hi"

(property) remarkPlugins?: PluggableList | null | undefined

(alias) function remarkFrontmatter(options?: Options | null | undefined): undefined
import remarkFrontmatter

(alias) compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

const file: "# hi"

(property) remarkPlugins?: PluggableList | null | undefined

(alias) function remarkGfm(options?: Options | null | undefined): undefined
import remarkGfm

(alias) function remarkFrontmatter(options?: Options | null | undefined): undefined
import remarkFrontmatter

(alias) compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

const file: "# hi"

(property) remarkPlugins?: PluggableList | null | undefined

(alias) function remarkGfm(options?: Options | null | undefined): undefined
import remarkGfm

(property) singleTilde: boolean

(alias) function remarkFrontmatter(options?: Options | null | undefined): undefined
import remarkFrontmatter

(alias) compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

const file: "# hi"

(property) rehypePlugins?: PluggableList | null | undefined

(alias) function rehypeKatex(options?: Readonly<Options> | null | undefined): (tree: Root, file: VFile) => undefined
import rehypeKatex

(property) remarkPlugins?: PluggableList | null | undefined

(alias) function remarkMath(options?: Readonly<Options> | null | undefined): undefined
import remarkMath

(alias) compile(vfileCompatible: Readonly<Compatible>, compileOptions?: Readonly<CompileOptions> | null | undefined): Promise<VFile>
import compile

const file: "# hi"

(property) rehypePlugins?: PluggableList | null | undefined

(alias) function rehypeKatex(options?: Readonly<Options> | null | undefined): (tree: Root, file: VFile) => undefined
import rehypeKatex

(property) strict: boolean

(property) throwOnError: boolean

(property) remarkPlugins?: PluggableList | null | undefined

(alias) function remarkMath(options?: Readonly<Options> | null | undefined): undefined
import remarkMath

创建插件

¥Creating plugins

为 MDX 创建插件与为 remark、rehype 或 recma 创建插件大致相同。§ 在 unifiedjs.com 上学习中有一些关于这方面的指南和秘诀。

¥Creating a plugin for MDX is mostly the same as creating a plugin for remark, rehype, or recma. There are several guides and recipes on that in § Learn on unifiedjs.com.

对于插件的 MDX 特定部分，建议阅读 ¶ 架构以了解 @mdx-js/mdx 的工作原理。有关代表 MDX 特定功能的节点类型的信息，请参阅 ¶ remark-mdx 中的语法树并使用我们的交互式 § 在线运行。

¥For the MDX specific parts of plugins, it’s recommended to read ¶ Architecture to learn how @mdx-js/mdx works. For info on the node types that represent MDX specific features, see ¶ Syntax tree in remark-mdx and use our interactive § Playground.

扩展 MDX

内容

组件和插件

组件清单

插件列表

使用插件

Notes

Notes

Notes

Notes

创建插件