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
  • List of components
  • List of plugins
• Using plugins
• Creating plugins

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 provider
• system-ui/theme-ui — React components for building consistent apps, integrates w/ MDX provider

List of plugins

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

• domdomegg/recma-mdx-displayname — add a displayName to MDXContent components, to enable switching on them in production
• remcohaszing/recma-nextjs-static-props — generate getStaticProps exposing top level identifiers in Next.js
• remcohaszing/rehype-mdx-title — expose the page title as a string
• remcohaszing/remark-mdx-code-meta — interpret the code meta field as JSX props
• remcohaszing/remark-mdx-images — change image sources to JavaScript imports
• remcohaszing/remark-mdx-frontmatter — change frontmatter (YAML) metadata to exports
• goodproblems/remark-mdx-math-enhanced — enhance math with JavaScript inside it
• pangelani/remark-mdx-chartjs — replace fenced code blocks with charts using react-chartjs-2.

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.