Skip to content
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

Closed
Tracked by #5848
slorber opened this issue Jan 12, 2021 · 33 comments · Fixed by #8288
Closed
Tracked by #5848

Migrate to MDX 2.0 #4029

slorber opened this issue Jan 12, 2021 · 33 comments · Fixed by #8288
Labels
domain: dependencies Proposal to upgrade a dependency across major versions domain: markdown Related to Markdown parsing or syntax proposal This issue is a proposal, usually non-trivial change
Milestone

Comments

@slorber
Copy link
Collaborator

slorber commented Jan 12, 2021

🚀 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! 🙏

@slorber slorber added feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. status: needs triage This issue has not been triaged by maintainers labels Jan 12, 2021
@armano2
Copy link
Contributor

armano2 commented Mar 22, 2021

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
Copy link
Collaborator Author

slorber commented Mar 22, 2021

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.

@lunelson
Copy link

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
Copy link

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
Copy link
Contributor

lex111 commented Sep 16, 2021

@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
Copy link

pomber commented Oct 13, 2021

MDX v2 release candidate landing soon

@slorber
Copy link
Collaborator Author

slorber commented Oct 19, 2021

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

image

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

@Josh-Cena Josh-Cena added this to the 2.0.0 milestone Oct 29, 2021
@Josh-Cena Josh-Cena added proposal This issue is a proposal, usually non-trivial change and removed feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. status: needs triage This issue has not been triaged by maintainers labels Oct 30, 2021
@Josh-Cena Josh-Cena added the status: blocked This issue is blocked by another issue or external dep and can't be pushed further. label Nov 14, 2021
@parsnips
Copy link

parsnips commented Nov 17, 2021

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
Copy link
Collaborator Author

slorber commented Nov 29, 2021

Nextra just upgraded in their 2.0 beta.

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

(except maybe the ESM support 😅 )

@jgarrow
Copy link
Contributor

jgarrow commented Mar 23, 2023

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
Copy link

😄 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
Copy link
Collaborator

@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
Copy link
Collaborator Author

slorber commented Apr 7, 2023

😄 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
Copy link
Collaborator Author

slorber commented Apr 21, 2023

  • 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! 🙏

@slorber slorber removed the status: blocked This issue is blocked by another issue or external dep and can't be pushed further. label Apr 21, 2023
@chendrix
Copy link

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
Copy link
Contributor

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
Copy link
Contributor

ilg-ul commented May 28, 2023

this is for the 3.0 release

Any tentative release date for it?

@RudraSen2
Copy link
Contributor

this is for the 3.0 release

Any tentative release date for it?

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

@slorber
Copy link
Collaborator Author

slorber commented May 30, 2023

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
Copy link
Collaborator Author

slorber commented Jun 9, 2023

Struggling to upgrade your site to MDX v2?

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
domain: dependencies Proposal to upgrade a dependency across major versions domain: markdown Related to Markdown parsing or syntax proposal This issue is a proposal, usually non-trivial change
Projects
None yet
Development

Successfully merging a pull request may close this issue.