MDX v3 - Remark/Rehype Plugins Support

[slorber]

Docusaurus v3 is around the corner, coming with MDX v3.

Please use this discussion to ask questions about the creation of Remark or Rehype plugins using MDX v3, or the upgrade of existing plugins to support MDX v3.

Note:

• This support is best effort, and technically it is kind-of outside the scope of Docusaurus. You should read Remark/Rehype/MDAST/HAST docs and changelogs to understand how to write or upgrade your plugins.
• Docusaurus doesn't even use any Rehype plugin internally to it's even harder for us to help you on this side. We have more experience using Remark.
• In general, we won't try to help if you don't invest your own time to expose your problem super clearly. We are not there to code the plugin for you, and you should be ready to get your hands dirty. At best we can "unlock" you. If you want someone to create/upgrade a plugin for you, contact a Docusaurus Service Provider.

Other useful support links

• Docusaurus v3 - Upgrade Support
• Docusaurus v3 - Discord channel #migration-v2-to-v3
• MDX v3 - Upgrade Support
• MDX v3 - Remark/Rehype Plugins Support
• MDX v3 - Discord channel #migration-mdx-v3

Before asking for support

To ask for support, please:

• Check if someone else already asked a similar question
• Create a minimal repro using docusaurus.new
• Give us the path of your Remark/Rehype plugin, your test markdown file, what you see vs what you expect
• Spend some time explaining your problem clearly in a structured and concise way
• Paste full, clear error messages and provide screenshots if appropriate

It's not scalable to provide done-for-you support for all Docusaurus users looking to upgrade. Any support request not respecting those constraints will possibly be ignored.

If you want help, you need to invest your own time so that helping you is easy.

Alternatively, you can look for a paid Docusaurus Service Provider to help you.

Useful notes for plugin authors

MDX v3 is a major MDX upgrade coming with breaking changes that impact your existing plugins.

It is probable that you will need to rewrite those plugins to support MDX v3.

It is outside the scope of Docusaurus to reach you everything about how to write Remark/Rehype plugins for MDX v1 vs MDX v3. If you successfully learned how to create a MDX v1 plugin, you will have to re-learn again and follow the same process to create a MDX v3 plugin.

We recommend using the MDX Playground extensively to understand how the new MDX AST works. By comparing the AST of your input, and the AST of your desired output, you can find out which AST transformations your plugins should perform.

ESM-Only support

MDX v3 and all newer versions of Unified/Remark/Rehype packages all use ESM only, and dropped support for CommonJS.

This has implications, and you will eventually need to use dynamic ESM imports in your plugin code, and/or your Docusaurus config (using CommonJS) to import those ESM modules.

An example:

module.exports = async function configCreatorAsync() {
  const myPlugin = (await import('./myPlugin')).default;
  return {
    // site config...
  };
};

If you write unit tests for your plugins, you must know that Jest does not support ESM. You can either use a tool that supports ESM, or vendor the dependencies you use as CJS.

Vendoring many small packages to get Jest to work is super annoying to do but it works, and is it what Docusaurus does:

npx esbuild @mdx-js/mdx --bundle --platform=node --outfile=jest/vendor/@mdx-js__mdx.js
npx esbuild remark --bundle --platform=node --outfile=jest/vendor/remark.js
npx esbuild remark-mdx --bundle --platform=node --outfile=jest/vendor/remark-mdx.js
npx esbuild remark-directive --bundle --platform=node --outfile=jest/vendor/remark-directive.js
npx esbuild mdast-util-to-string --bundle --platform=node --outfile=jest/vendor/mdast-util-to-string.js
npx esbuild estree-util-value-to-estree --bundle --platform=node --outfile=jest/vendor/estree-util-value-to-estree.js
npx esbuild remark-gfm --bundle --platform=node --outfile=jest/vendor/remark-gfm.js
npx esbuild @mdx-js/mdx --bundle --platform=node --outfile=jest/vendor/@mdx-js__mdx.js
npx esbuild unified --bundle --platform=node --outfile=jest/vendor/unified.js
npx esbuild hast-util-raw --bundle --platform=node --outfile=jest/vendor/hast-util-raw.js
npx esbuild rehype-raw --bundle --platform=node --outfile=jest/vendor/rehype-raw.js

{
  moduleNameMapper: {
    // MDX packages are ESM-only and it is a pain to use in Jest
    // So we use them in Jest tests as CJS versions
    // see https://mdxjs.com/docs/troubleshooting-mdx/#problems-integrating-mdx
    '^unified$': '<rootDir>/jest/vendor/unified@10.1.2.js',
    '^@mdx-js/mdx$': '<rootDir>/jest/vendor/@mdx-js__mdx@2.1.5.js',
    '^remark$': '<rootDir>/jest/vendor/remark@14.0.2.js',
    '^remark-mdx$': '<rootDir>/jest/vendor/remark-mdx@2.1.5.js',
    '^remark-directive$': '<rootDir>/jest/vendor/remark-directive@2.0.1.js',
    '^remark-gfm$': '<rootDir>/jest/vendor/remark-gfm@3.0.1.js',
    '^estree-util-value-to-estree$':
      '<rootDir>/jest/vendor/estree-util-value-to-estree@2.1.0.js',
    '^mdast-util-to-string$':
      '<rootDir>/jest/vendor/mdast-util-to-string@3.1.0.js',
  }
}

New AST nodes

This new MDX version is much cleaner and stricter in how it represents JSX and ESM nodes in its AST.

For example, let's compare the AST o MDX v1/v3 for the same MDX file:

# Title

export function Hello({name}) {
  return <div>Hello {name}</div>
}

<Hello name="World"/>

MDX v1 MDAST will look like:

{
  "type": "root",
  "children": [
    {
      "type": "heading",
      "depth": 1,
      "children": [
        {
          "type": "text",
          "value": "Title",
        }
      ],
    },
    {
      "type": "export",
      "value": "export function Hello({name}) {\n  return <div>Hello {name}</div>\n}",
    },
    {
      "type": "jsx",
      "value": "<Hello name=\"World\"/>",
    }
  ],
}

MDX v3 MDAST will look like:

{
  "type": "root",
  "children": [
    {
      "type": "heading",
      "depth": 1,
      "children": [
        {
          "type": "text",
          "value": "Title"
        }
      ]
    },
    {
      "type": "mdxjsEsm",
      "value": "export function Hello({name}) {\n  return <div>Hello {name}</div>\n}",
      "data": {
        "estree": {
          "type": "Program",
          "start": 9,
          "end": 75,
          "body": [
            {
              "type": "ExportNamedDeclaration",
              "start": 9,
              "end": 75,
              "declaration": {
                "type": "FunctionDeclaration",
    	        /* Omitted - ESTree AST */
              },
            }
          ],
        }
      }
    },
    {
      "type": "mdxJsxFlowElement",
      "name": "Hello",
      "attributes": [
        {
          "type": "mdxJsxAttribute",
          "name": "name",
          "value": "World"
        }
      ],
      "children": [],
      "data": {
        "_mdxExplicitJsx": true
      }
    }
  ]
}

The first thing you should notice is that:

• MDX v1 relies much more on "raw strings"
• MDX v3 introduces new, clean AST nodes to represent ESM and JSX

The new node types are documented on the mdast-util-mdx-jsx and mdast-util-mdxjs-esm repositories:

• 'mdxFlowExpression'
• 'mdxJsxFlowElement'
• 'mdxJsxTextElement'
• 'mdxTextExpression'
• 'mdxjsEsm'

Plugin migration examples

• React-Native upgraded SnackPlayer Remark Plugin to MDX v3
• docusaurus-remark-plugin-tab-blocks upgraded to MDX v3
• Docusaurus MDX v3 PR upgrading many internal Remark plugins
• Docusaurus 3: how to migrate rehype plugins

Please tell us if you find good community examples, and we'll mention them here to help other plugin authors.

[johnnyreilly]

I plan to work on an upgrade to https://github.com/johnnyreilly/rehype-cloudinary-docusaurus - this is a reminder I need to do it

https://johnnyreilly.com/docusaurus-image-cloudinary-rehype-plugin#introducing-rehype-cloudinary-docusaurus

[johnnyreilly]

Are there any example Docusaurus rehype plugins that could be used for reference?

[slorber]

Hmm I don't think I ever worked on any Rehype plugin sorry 😅

[johnnyreilly]

I've been testing out the Docusaurus 3 beta which migrates to MDX 2. I have a couple of rehype plugins that improve core webvitals and serve images with cloudinary. This post walks through the migration for each plugin:

https://johnnyreilly.com/docusaurus-3-how-to-migrate-rehype-plugins