-
-
Notifications
You must be signed in to change notification settings - Fork 8.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Migrate to MDX 2.0 #4029
Comments
mdx 2.0 introduced breaking change, comments |
There are also disagreements in the MDX core contributors:
There's also a "fork" xdm project from Titus himself. Let's not rush on this migration for now and see how things evolve. |
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 |
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. |
@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). |
MDX v2 release candidate landing soon |
MDX 2 RC 👍 And there's a migration guide: https://v2.mdxjs.com/migrating/v2/ |
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 |
Nextra just upgraded in their 2.0 beta. Seems like it was not too hard to do this upgrade:
(except maybe the ESM support 😅 ) |
@scubamaggo did you ever get pomber's theme working with |
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. |
@dprothero We're probably not going to do that kind of naïve replacement. It would be contextual, so any code would be skipped. |
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. |
Please test it and give me some feedback here! 🙏 |
Am I to understand this isn't going to land in any of the |
yes. this is for the 3.0 release |
Any tentative release date for it? |
I don't know, You can ask the docusaurus team. |
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. |
Struggling to upgrade your site to MDX v2? Here's a discussion to ask for support: #9053 |
🚀 Feature
We should migrate to MDX 2.0
PR: #8288
Update
Please test it and give me some feedback here! 🙏
The text was updated successfully, but these errors were encountered: