Mdx: MDX v2: ☂️ Umbrella issue

Created on 30 Apr 2020  ·  9Comments  ·  Source: mdx-js/mdx

👋 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 #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 #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?

💎 v2 💬 typdiscussion 📣 typannouncement 🔍 statuopen 🦋 typenhancement 🧑 semvemajor
Source
picture johno
👍32 🎉22 ❤17 👀5

Most helpful comment

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.

picture johno on 17 Jun 2020
👍8 🎉4 ❤1

All 9 comments

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

chasemccoy picture chasemccoy on 1 May 2020
👍3 ❤1

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.

codebender828 picture codebender828 on 1 May 2020
🚀3

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

johno picture johno on 1 May 2020

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

codebender828 picture codebender828 on 2 May 2020

Is it possible to solve vscode's IntelliSense problem? https://github.com/mdx-js/vscode-mdx/issues/56

nightwind2020 picture nightwind2020 on 8 May 2020
👍4

@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)

https://github.com/storybookjs/storybook/issues/9311

shilman picture shilman on 7 Jun 2020
❤3 👀2

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 picture johno on 17 Jun 2020
👍8 🎉4 ❤1

what about #702 ? (passing Code props as JSX instead of string)
It's a breaking change and would fit nicely with the rest of v2.

KutnerUri picture KutnerUri on 17 Dec 2020

I think we can drop:

  • Create an mdx package that includes all packages with exports like: mdx/react and mdx/vue

I don’t really see a use for it personally.

(I’ve updated some of the others that are done or are solved in other ways)

Everything else that’s left to do still makes sense to me for v2

wooorm picture wooorm on 20 Dec 2020
👍2
Was this page helpful?
0 / 5 - 0 ratings

Related issues

mAAdhaTTah picture mAAdhaTTah  ·  4Comments
lex111 picture lex111  ·  4Comments
johno picture johno  ·  3Comments
deligent-ant picture deligent-ant  ·  3Comments
Exelord picture Exelord  ·  4Comments