MDX 3

Version 3 already! This major version contains a couple small changes. For most folks, updating Node.js and plugins is all that’s needed!

Contents

• Breaking changes
• Improvements to the MDX format
  • Adjacent block JSX and expressions in MDX
  • Await in MDX
  • ES2024 in MDX
• Miscellaneous
• Thanks

Breaking changes

The main breaking change is that Node.js 16 is now the minimum supported version.

Across the ecosystem there were several small internal breaking changes. Everything’s released already. You can update all plugins now. If you ran into problems before, it should work now.

We also removed some infrequently used deprecated APIs. You’re likely fine but gloss over the v3 migration guide if you get errors.

Important to note when you use your lesser-known but powerful evaluate, run, or outputFormat: 'function-body' APIs, please pass the baseUrl option. That makes sure import.meta.url, import, and export work. You’ll get a runtime error when those features are used otherwise.

Improvements to the MDX format

There’s also a few small improvements to the MDX format, some of which technically breaking.

Adjacent block JSX and expressions in MDX

We now accept block expressions right next to block JSX tags:

<style>{`

  h1 {
    color: blue;
  }

`}</style>

Previously, there was a syntax error, and you had to add a newline between the angle brackets and the braces.

Await in MDX

We now accept await syntax:

{await Promise.resolve(42)}

Most frameworks don’t support promises. Whether this works depends on that.

Previously, there was a runtime error that await was used in a context where it wasn’t allowed.

ES2024 in MDX

You can now use modern JavaScript syntax in MDX. Acorn, used internally, is now instructed to use ES2024.

Miscellaneous

I refactored all the docs. Updating every use example where needed. I also wrote a guide on how to inject components from anywhere: § Injecting components.

The site is a lot faster. There’s a nice improved playground too: try it out! ». We also have proper syntax highlighting here, thanks to wooorm/markdown-tm-language and wooorm/starry-night.

The generated JS code is a little cleaner (the JSX pragma comment is removed and objects are sorted where needed), it also uses spreads instead of Object.assign, there’s a 'use strict' added when needed, and the MDXContent is exported immediately.

Thanks

We’d like to say thanks to all our contributors and our happy users. Special thanks to 北雁云依 (@BeiyanYunyi), Christian Murphy (@ChristianMurphy), JokcyLou (@Jokcy), Maël Nison (@arcanis), Andreas Deininger (@deining), Remco Haszing (@remcohaszing), Sébastien Lorber (@slorber), Víctor Fernández (@victor23k), Titus Wormer (@wooorm), and anyone we may have forgotten.