Skip to navigation

扩展 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 耦合。例如，如果你使用 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

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

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

插件列表

¥List of plugins

另请参见 remark 插件列表 和 rehype 插件列表。

¥See also the list of remark plugins and list of rehype plugins.

注意：有另一个专门与 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 插件位于 ProcessorOptions 的 rehypePlugins 中。这些字段需要插件和/或 [plugin, options] 的列表：

¥Where to pass plugins is encoded in their name: remark plugins go in remarkPlugins and rehype plugins go in rehypePlugins 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]
})

创建插件

¥Creating plugins

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

¥Creating a plugin for MDX is mostly the same as creating a plugin for remark or rehype. 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 中文网 - 粤ICP备13048890号