Migrate to MDX 2.0

[slorber]

🚀 Feature

We should migrate to MDX 2.0

PR: #8288

---

Update

• The MDX 2 PR has been merged
• I documented many breaking changes and provided some compatibility options (see PR)
• A canary release is now available (>= 0.0.0-5556)
• Need support to upgrade to MDX v2? See MDX v2 Upgrade Support

Please test it and give me some feedback here! 🙏

[armano2]

mdx 2.0 introduced breaking change, comments <!-- --> are not longer allowed in code, and thus mdxjs can't be used for simple markdown files

[slorber]

There are also disagreements in the MDX core contributors:

• Remove runtime renderer, still support MDXProvider mdx-js/mdx#1425
• An alternative “shortcode” (mdxType alternative) proposal mdx-js/mdx#1385

There's also a "fork" xdm project from Titus himself.

Let's not rush on this migration for now and see how things evolve.

[lunelson]

I strongly encourage using xdm, it's a simpler, faster and more stable pipeline, it is always in sync with the remark/rehype ecosystem and its development is moving quickly

[birdofpreyru]

Ok, @lex111, probably then add a warning block to the top of https://docusaurus.io/docs/markdown-features/react page, saying that current Docusaurus uses MDX v1? Cause I believe the current docs do not mention it, and the linked MDX site pages do not make it clear that there are two version with some features not supported in v1.

[lex111]

@birdofpreyru alright, although it seems self-evident for now, because MDX v2 is not officially released. However, the migration to MDX v2 will probably not be that easy, so it makes sense to do it (see #5575).
FYI, earlier in header of MDX website listed its latest version, but currently they have removed that info.

[pomber]

MDX v2 release candidate landing soon

[slorber]

MDX 2 RC 👍
https://v2.mdxjs.com/blog/v2/

And there's a migration guide: https://v2.mdxjs.com/migrating/v2/

[parsnips]

Would really love to get to v2 to have things like: mdx-js/mdx#821

This would be a tremendous help for porting in plain markdown documents that have <pre /> or inline html fragments.

[slorber]

Nextra just upgraded in their 2.0 beta.

Seems like it was not too hard to do this upgrade:

• Fix GFM support and upgrade MDX loader shuding/nextra#184
• fix for MDXProvider/TOC, and bump mdx version to 2.0.0-rc2  shuding/nextra#251

(except maybe the ESM support 😅 )

[jgarrow]

FWIW: I tried to start from @pomber's theme and integrate remark-directive. Most updates were fairly simple, following this guide https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c. I ran into a wall when I declared the mdx-loader as a type "module" to be interpreted by webpack. While the loader-runner is already able to load loaders via import(), webpack itself does not seem ready for it: webpack/loader-runner@4f91458#r40502100

@scubamaggo did you ever get pomber's theme working with remark-directive? I am working with the same theme; my Docusaurus site compiles fine, but remark-directive doesn't seem to be doing anything

[dprothero]

😄 This is the processing layer I'm thinking of: str.replaceAll('<!--', '\\<!--')

I know I'm late to the party, @slorber, but are we worried about code samples here? I could see that replacement potentially breaking an HTML snippet in a code fence.

[Josh-Cena]

@dprothero We're probably not going to do that kind of naïve replacement. It would be contextual, so any code would be skipped.

[slorber]

😄 This is the processing layer I'm thinking of: str.replaceAll('<!--', '\\<!--')

I know I'm late to the party, @slorber, but are we worried about code samples here? I could see that replacement potentially breaking an HTML snippet in a code fence.

The way I see it is that I'll add a few env variables to turn compatibility options on. To make the upgrade simpler you'll be able to turn all the env variables on, and once you have fully migrated to MDX 2 you could remove the env variables.

Will probably add an option to turn this on: https://github.com/leebyron/remark-comment (or maybe it will simply work if you pass it as a remark plugin, didn't try that yet)

I also think I'll allow you to provide your own preprocessor so that you can handle the most complex cases yourself.

[slorber]

• The MDX 2 PR has been merged
• I documented many breaking changes and provided some compatibility options (see PR)
• A canary release is now available (>= 0.0.0-5556)

Please test it and give me some feedback here! 🙏

[chendrix]

Am I to understand this isn't going to land in any of the 2.x releases and is being saved for 3.0.0?

[RudraSen2]

Am I to understand this isn't going to land in any of the 2.x releases and is being saved for 3.0.0?

yes. this is for the 3.0 release

[ilg-ul]

this is for the 3.0 release

Any tentative release date for it?

[RudraSen2]

this is for the 3.0 release

Any tentative release date for it?

I don't know, You can ask the docusaurus team.

[slorber]

This is a breaking change, and it is very likely that upgrading to Docusaurus v3 + MDX v2 will require you to edit some docs to fix some little issues due to those changes.

So no it won't be in v2.x

I hope to release the v3 first alphas soon.

In the meantime, you already are able to use the canary releases. Canaries are safe to use in production if you pin the canary version. In the end, the v3 release will just be a future canary release tagged as v3.

[slorber]

Struggling to upgrade your site to MDX v2?

Here's a discussion to ask for support: #9053