MDX Plugins

Sometimes, you may want to extend or tweak your Markdown syntax. For example:

• How do I embed youtube videos using the image syntax (![](https://youtu.be/yKNxeF4KMsY))?
• How do I style links that are on their own lines differently, e.g., as a social card?
• How do I make every page start with a copyright notice?

And the answer is: create an MDX plugin! MDX has a built-in plugin system that can be used to customize how the Markdown files will be parsed and transformed to JSX. There are three typical use-cases of MDX plugins:

• Using existing remark plugins or rehype plugins;
• Creating remark/rehype plugins to transform the elements generated by existing MDX syntax;
• Creating remark/rehype plugins to introduce new syntaxes to MDX.

If you play with the MDX playground, you would notice that the MDX transpilation has two intermediate steps: Markdown AST (MDAST), and Hypertext AST (HAST), before arriving at the final JSX output. MDX plugins also come in two forms:

• Remark: processes the Markdown AST.
• Rehype: processes the Hypertext AST.

Docusaurus injects some default Remark plugins during Markdown processing. These plugins would:

• Generate the table of contents;
• Add anchor links to each heading;
• Transform images and links to require() calls.
• …

These are all typical use-cases of Remark plugins, which can also be a source of inspiration if you want to implement your own plugin.

An MDX plugin is usually an npm package, so you install them like other npm packages using npm. Take the math plugins as an example.

npm install --save remark-math rehype-katex

Next, import your plugins and add them to the plugin options through plugin or preset config in docusaurus.config.js:

import remarkMath from 'remark-math';import rehypeKatex from 'rehype-katex';export default {  presets: [    [      '@docusaurus/preset-classic',      {        docs: {          path: 'docs',          remarkPlugins: [remarkMath],          rehypePlugins: [rehypeKatex],        },      },    ],  ],};

module.exports = async function createConfigAsync() {  return {    presets: [      [        '@docusaurus/preset-classic',        {          docs: {            path: 'docs',            remarkPlugins: [(await import('remark-math')).default],            rehypePlugins: [(await import('rehype-katex')).default],          },        },      ],    ],  };};

Some plugins can be configured and accept their own options. In that case, use the [plugin, pluginOptions] syntax, like this:

import rehypeKatex from 'rehype-katex';export default {  presets: [    [      '@docusaurus/preset-classic',      {        docs: {          rehypePlugins: [            [rehypeKatex, {strict: false}],          ],        },      },    ],  ],};

You should check your plugin's documentation for the options it supports.

If there isn't an existing package that satisfies your customization need, you can create your own MDX plugin.

For example, let's make a plugin that visits every h2 heading and adds a Section X. prefix. First, create your plugin source file anywhere—you can even publish it as a separate npm package and install it like explained above. We would put ours at src/remark/section-prefix.js. A remark/rehype plugin is just a function that receives the options and returns a transformer that operates on the AST.

import {visit} from 'unist-util-visit';

const plugin = (options) => {
  const transformer = async (ast) => {
    let number = 1;
    visit(ast, 'heading', (node) => {
      if (node.depth === 2 && node.children.length > 0) {
        node.children.unshift({
          type: 'text',
          value: `Section ${number}. `,
        });
        number++;
      }
    });
  };
  return transformer;
};

export default plugin;

You can now import your plugin in docusaurus.config.js and use it just like an installed plugin!

import sectionPrefix from './src/remark/section-prefix';export default {  presets: [    [      '@docusaurus/preset-classic',      {        docs: {          remarkPlugins: [sectionPrefix],        },      },    ],  ],};