search

mdx-js / mdx

Markdown for the component era
https://mdxjs.com
MIT License
17.4k stars 1.14k forks source link

MDX v2: ☂️ Umbrella issue #1041

Closed johno closed 2 years ago

johno commented 4 years ago

👋 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

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?

chasemccoy commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

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

codebender828 commented 4 years ago

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

timedtext commented 4 years ago

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

shilman commented 4 years ago

@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

johno commented 4 years ago

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.

KutnerUri commented 3 years ago

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.

wooorm commented 3 years ago

I think we can drop:

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

mrhut10 commented 3 years ago

can't wait for the Interleaving Markdown in JSX feature.

in my blog would love to have a tabbed experiance arround codeblocks to show examples in multiple languages, i.e. javascript and typescript

<TabsHolder>
<Tab title="javascript">
  /```
    // im some javascript code
  /```
</Tab>
<Tab title="typescript">
  /```
    // im some typescript code
  /```
</Tab>
<TabsHolder>
mattly commented 3 years ago

can't wait for the Interleaving Markdown in JSX feature.

You can already do this, you just have to pad the inner contents of the component with a newline. An example from my blog: https://github.com/mattly/lyonheart-us/blame/main/src/articles/consuming-graphql-simply/index.mdx#L136-L140

in my blog would love to have a tabbed experiance arround codeblocks to show examples in multiple languages, i.e. javascript and typescript

<TabsHolder>
<Tab title="javascript">
  /```
    // im some javascript code
  /```
</Tab>
<Tab title="typescript">
  /```
    // im some typescript code
  /```
</Tab>
<TabsHolder>

I'm using Gatsby, but I implemented a component that does this.

Personally, I'm still waiting on the bugfix which will render a paragraph that starts with an inline component the same as one that merely contains one in the middle of it.

jsamr commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

axe312ger commented 2 years ago

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 commented 2 years ago

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: https://github.com/wooorm/xdm/issues/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 commented 2 years ago

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

axe312ger commented 2 years ago

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

theoludwig commented 2 years ago

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 commented 2 years ago

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.

kachkaev commented 2 years ago

That is amazing! 🎉 🎉 🎉

I have just created an issue in Prettier to discuss MDX 2 support: https://github.com/prettier/prettier/issues/12209

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