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

MDX v2: ☂️ Umbrella issue #1041

Closed
16 of 25 tasks
Tracked by #10150
johno opened this issue Apr 30, 2020 · 21 comments
Closed
16 of 25 tasks
Tracked by #10150

MDX v2: ☂️ Umbrella issue #1041

johno opened this issue Apr 30, 2020 · 21 comments
Labels
💪 phase/solved Post is done 🧑 semver/major This is a change 📣 type/announcement This is meta 💎 v2 Issues related to v2
Milestone

Comments

@johno
Copy link
Member

johno commented Apr 30, 2020

👋 Hey folks, the time has come to begin putting together MDX v2. We've been aggregating feedback, working on parsing, and we think we now have all of our 🦆🦆🦆🦆 ducks in a line to begin releasing a next tag in the next week.

Please note: Nothing written here is final and we'd love for contributors, users, and anyone else to comment with ideas, opinions, and questions/concerns.

Features

  • 🤖Drastically improved parsing led by @wooorm in Rewrite how MDX is parsed #1039. This will handle a wide array of parsing issues that have been brought up over the last year with a robust solution. The new parser will address a large amount of papercuts users have been working around for far too long. It also adds JSX usage into the AST which will allow users to perform their own transforms with plugins. One of the more notable additions here is the ability to support expressions throughout a document (also a breaking change).
  • 🚀Official Vue support led by @codebender828 and @ChristopherBiscardi in Vue, rebased #1029. The previous alpha implementation of Vue was buggy and not updated with MDX as it evolved. We no longer have a custom transpiler for Vue and only have to implement a custom renderer/pragma. This is so huge and we're delighted @codebender828 took on this monumental effort.
  • 🧩TypeScript support led by @ChristianMurphy. The public facing packages feature official types with tests.

Breaking changes?

Generally speaking, most of the breaking changes will be internal and shouldn't directly affect end users. We haven't yet shipped them, though, because they are technically changing behavior users may've been depending on (which will be documented below).

However, with the parsing overhaul (#1039) the syntax has been formalized which will likely cause issues for characters that aren't HTML encoded, < and {, (some of which we'll be able to address with codemods).

RFCs

The following RFCs (request for comments) are either accepted (✅), being discussed (💬), declined (✖️), or need to be written (📝). If you have opinions here, please chime in on these issues as they will affect the v2 release.

Work left to complete or currently in flight

If you have any interest in working on any of these tasks please let us know! We'd be happy to help guide anyone along.

Encountered bugs

Performance considerations

How can you help?

Let us know if you want to take on any of the issues that don't yet have folks assigned. You can also take the canary for a spin and let us know if you encounter any problems:

yarn add @mdx-js/mdx@next @mdx-js/react@next

Is there something missing? Is there something you're concerned about?

@johno johno added 🦋 type/enhancement This is great to have 💬 type/discussion This is a request for comments 💎 v2 Issues related to v2 🧑 semver/major This is a change 🔍 status/open 📣 type/announcement This is meta labels Apr 30, 2020
@johno johno pinned this issue Apr 30, 2020
@chasemccoy
Copy link
Contributor

This is so exciting to see! When the time is right, I’d be happy to help test this with our design system: https://seeds.sproutsocial.com

@codebender828
Copy link
Contributor

Thanks @johno ! Excited for this to progress. I guess the first thing we can do for the Vue package is to work on the documentation so we can get some people to use it and gather some feedback. Then when it's stable we can see how to normalize the MDX rendering props and attrs for Vue in mdx v2.

@johno
Copy link
Member Author

johno commented May 1, 2020

For sure @codebender828! Are you interested in owning that (#851)?

@codebender828
Copy link
Contributor

codebender828 commented May 2, 2020

@johno
Yes! Sounds good! Where's the best place to get started with familiarizing myself with the docs?

@timedtext
Copy link

Is it possible to solve vscode's IntelliSense problem? mdx-js/mdx-analyzer#56

@shilman
Copy link

shilman commented Jun 7, 2020

@johno worst question ever, but any updated ETA on this? we've added a bit of scope to Storybook 6 and are looking at RC late june and final release late july. would be amazing to make MDX2 part of that. and--since it's a breaking change--pretty bad if we can't, since we try to limit our major release cycle to once per year (tho we're not religious about that)

storybookjs/storybook#9311

@johno
Copy link
Member Author

johno commented Jun 17, 2020

Hey @shilman, we're hoping for an RC in the by June, and if all goes well a mid July release. Generally speaking, the breaking changes should be pretty light because they're generally internals aside from the new parsing changes (which we will also offer a codemod that should address most problems that might arise).

Hopefully this corresponds nicely with you folks? I'm pretty busy this week with other things, but plan on picking MDX v2 back up full time starting next week.

@johno johno added this to the v2 milestone Jul 22, 2020
wooorm added a commit that referenced this issue Dec 11, 2020
This updates MDX to use and support remark@13, which comes with a new internal
parser (micromark), and supports CommonMark.
See <https://github.com/remarkjs/remark/releases/tag/13.0.0> for more
information.
In short, this means MDX parses markdown closer to what folks expect.
And it means all latest plugins work (again).

But it also means that parsing MDX syntax (JSX, expressions, ESM) got an update.
See: <https://github.com/micromark/micromark-extension-mdxjs> and
<https://github.com/syntax-tree/mdast-util-mdx> for the syntax.
In short, this means MDX parsing is now JavaScript-aware: import/exports are
actually parsed for being valid JavaScript.
Expressions previously counted braces, but now can include braces in strings or
comments or whatnot.
This also means we can drop Babel (in a future PR) because we already have a
JavaScript AST.

This also deprecates the packages `remark-mdxjs` (which is now the default in
`remark-mdx`), `remark-mdx-remove-exports`, and `remark-mdx-remove-imports`.

Related to GH-704.
Related to GH-1041.

Closes GH-720.
Closes GH-1028.
Closes GH-1050.
Closes GH-1081.
Closes GH-1193.
Closes GH-1238.
Closes GH-1283.
Closes GH-1316.
Closes GH-1318.
Closes GH-1341.
@jsamr
Copy link

jsamr commented Apr 30, 2021

I think I've spotted an edge-case issue with mixed html / md (@mdx-js/react@2.0.0-next.9). See for example this:

<abbr title="Foo Bar">FB</abbr>, I like [links](https://domain.org)

will render as:

<p>
  <abbr title="Foo Bar">FB</abbr>, I like [links](https://domain.org)
</p>

instead of

<p>
  <abbr title="Foo Bar">FB</abbr>, I like <a href="https://domain.org">links</a>
</p>

The workaround I've found is to add a zero-width space at the beginning of the line, like so:

&ZeroWidthSpace;<abbr title="Foo Bar">FB</abbr>, I like [links](https://domain.org)

@axe312ger
Copy link

Is there any way to "simply" test it with my Gatsby websites? I'd love to give it a try and report back bugs :)

@axe312ger
Copy link

A new version was released. Progress. LOVELY!!!

@axe312ger
Copy link

Is there any way to "simply" test it with my Gatsby websites? I'd love to give it a try and report back bugs :)

@wooorm Hey! You just released the RC-1. That is awesome! Can I support you? Is there a way to try it out with Gatsby? :)

Thank you so much!!!

@wooorm
Copy link
Member

wooorm commented Oct 20, 2021

Hey! Thanks for the kind words. You can indeed support MDX and the underlying projects (and me). To help out financially, see Sponsor on the site. A big part of helping is also just helping out in repos, as in, contributing. See Contribute on the website.

Unfortunately Gatsby integrates heavily with the internals of MDX. That allows Gatsby to do some cool things, and has allowed them to apply other improvements specific to Gatsby, but it means you can’t just switch to the RC of V2 in Gatsby.

It is possible. But hard. @thecodingwizard made it work in cpinitiative/usaco-guide: https://github.com/cpinitiative/usaco-guide. The relevant discussion is here: wooorm/xdm#40. If anyone tries this, swap xdm out with @mdx-js/* — they’re almost identical.

I am assuming that Gatsby will work on adding support for Version 2 themselves though! :)

@axe312ger
Copy link

@wooorm Alright, thank you. I contribute to Gatsby itself, so I'll see if I can help over there.

@axe312ger
Copy link

I'll consider financial support as soon the rebranding of my tiny agency is done :)

@theoludwig
Copy link

Can we have an estimate of the v2 release date?
If there is anything blocking, needs to be done or how can we help to move things forward?

@wooorm wooorm added 💪 phase/solved Post is done and removed 🦋 type/enhancement This is great to have 💬 type/discussion This is a request for comments 🙉 open/needs-info This needs some more info labels Feb 1, 2022
@wooorm
Copy link
Member

wooorm commented Feb 1, 2022

Hey all!

V2 was finally released, thanks for everyone who contributed, and for everyone who waited! ✨ More on v2 in the release and on the site: https://github.com/mdx-js/mdx/releases/tag/2.0.0.

@wooorm wooorm closed this as completed Feb 1, 2022
@kachkaev
Copy link

kachkaev commented Feb 1, 2022

That is amazing! 🎉 🎉 🎉

I have just created an issue in Prettier to discuss MDX 2 support: prettier/prettier#12209

Feel free to contribute with your thoughts 🙌 (or code 🙏 )

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
💪 phase/solved Post is done 🧑 semver/major This is a change 📣 type/announcement This is meta 💎 v2 Issues related to v2
Development

No branches or pull requests

14 participants