import {Note} from '../_component/note.jsx'
export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], modified: new Date('2023-01-19'), published: new Date('2021-10-06') } export const navSortSelf = 4
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.
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.
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
{/* please use alpha sorting on project name! You can use this template:
user/project
— A somewhat short description of the project */}
See also the list of remark plugins and list of rehype plugins.
remcohaszing/recma-export-filepath
— export the filepathipikuka/recma-mdx-change-props
— changes the param as_props
in the_createMdxContent
functiondomdomegg/recma-mdx-displayname
— add adisplayName
toMDXContent
components, to enable switching on them in productionipikuka/recma-mdx-escape-missing-components
— set a default value of() => null
for missing components instead of throwing an errorremcohaszing/recma-mdx-is-mdx-component
— add anisMdxComponent
field on MDX componentsremcohaszing/recma-nextjs-static-props
— generategetStaticProps
exposing top level identifiers in Next.jsremcohaszing/rehype-mdx-code-props
— interpret the codemeta
field as JSX propsremcohaszing/rehype-mdx-import-media
— change media sources to JavaScript importsremcohaszing/rehype-mdx-title
— expose the page title as a stringpangelani/remark-mdx-chartjs
— replace fenced code blocks with charts usingreact-chartjs-2
.remcohaszing/remark-mdx-frontmatter
— change frontmatter (YAML) metadata to exportsgoodproblems/remark-mdx-math-enhanced
— enhance math with JavaScript inside it
{/* please use alpha sorting on project name! You can use this template:
user/project
— a somewhat short description of the project */}
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]
:
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 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.