By Titus Wormer
Note: V2 is around the corner. This website is for that. It hasn’t been released yet. But you can try out the RC. You can be of great help by reading through these docs and letting us know what’s confusing or wrong or other suggestions you have. See § Support for where to ask questions and § Contribute for how to help.
Extending 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
There are three extension points when using @mdx-js/mdx or one of its integrations:
- Options passed to the compiler (see ¶ API in
@mdx-js/mdx) - Plugins that hook into several stages of compilation (see remark plugins, rehype plugins, and the new recma plugins)
- Components passed, defined, or imported at runtime (see § Using 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— React components for embedding 3rd party content, integrates w/ MDX providersystem-ui/theme-ui— React components for building consistent apps, integrates w/ MDX provider
Note: have another component that specifically works with MDX? Please send a PR to add it here!
List of plugins
See also the list of remark plugins and list of rehype plugins.
remcohaszing/rehype-mdx-title— expose the page title as a stringremcohaszing/remark-mdx-code-meta— interpret the codemetafield as JSX propsremcohaszing/remark-mdx-images— change image sources to JavaScript importsremcohaszing/remark-mdx-frontmatter— change frontmatter (YAML) metadata to exports
Note: have another unified plugin that specifically works with MDX? Please send a PR to add it here!
Using plugins
Where to pass plugins is encoded in their name: remark plugins go in options.remarkPlugins, rehype plugins in options.rehypePlugins. Those fields expect lists of plugins and/or of [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, {remarkPlugins: [remarkMath], rehypePlugins: [rehypeKatex]})
// remark and rehype plugins, last w/ options:
await compile(file, {
remarkPlugins: [remarkMath],
// A plugin with options:
rehypePlugins: [[rehypeKatex, {throwOnError: true, strict: true}]]
})
Creating plugins
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.
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.