extending-mdx.mdx

import {Note} from '../_component/note.jsx'

export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer'} ], modified: new Date('2025-01-27'), published: new Date('2021-10-06') } export const navSortSelf = 4

Extending MDX

This article explains how to extend MDX content—specifically, how to transform content with plugins. {/* more */} 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 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

• mdx-embed — React components for embedding 3rd party content, integrates w/ MDX provider
• theme-ui — React components for building consistent apps, integrates w/ MDX provider

{/*

• Please use alpha sorting on project name!
• You can use this template:
• • package
• — somewhat short description of the project

*/}

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

List of plugins

MDX-specific remark plugins

• remark-directive-mdx — transform Markdown directives (:directive[]) to JSX elements
• remark-mdx-chartjs — replace fenced code blocks with charts using react-chartjs-2.
• remark-mdx-frontmatter — change frontmatter (YAML) metadata to exports
• remark-mdx-math-enhanced — enhance math with JavaScript inside it
• remark-mdx-remove-esm — remove import and/or export statements (mdxjsEsm)
• remark-mdx-remove-expressions — remove MDX expressions within curlybraces {} in MDX content

See also the list of remark plugins.

MDX-specific rehype plugins

• rehype-mdx-code-props — interpret the code meta field as JSX props
• rehype-mdx-import-media — change media sources to JavaScript imports
• rehype-mdx-title — expose the page title as a string
• rehype-mdx-toc — export the table of contents data into MDX module

See also the list of rehype plugins.

MDX-specific recma plugins

• recma-export-filepath — export the filepath
• recma-mdx-change-props — changes the param as _props in the _createMdxContent function
• recma-mdx-displayname — add a displayName to MDXContent components, to enable switching on them in production
• recma-mdx-escape-missing-components — set a default value of () => null for missing components instead of throwing an error
• recma-mdx-is-mdx-component — add an isMdxComponent field on MDX components
• recma-nextjs-static-props — generate getStaticProps exposing top level identifiers in Next.js
• recma-module-to-function — convert a module into a function body

See also the list of recma plugins.

{/*

• Please use alpha sorting on package name!
• You can use this template:
• • package
• — somewhat short description of the project

*/}

**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 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]:

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

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.

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.