Skip to navigation
3-4 minutes read
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.


Components & plugins

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

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

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.

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

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.