Question: Regular Markdown HTML syntax ignored

[ovflowd]

Hey there 👋 I was wondering to get an answer on the following, I recall (when I used Gatsby) that regular Markdown .md files could still have HTML syntax such as <div class="something"> and it would still allow me to do something like <SomeJSXComponent /> if I passed on <MDXPRovider components={{ SomeJSXComponent: (something) => <div>hello there</div> }} />.

Of course, I'm assuming this based on my memory, but I just wanted to double-check if this is something actually supported on MDXv2, as I recall, it worked on MDXv1.

[wooorm]

Hey!

• Depends what you mean with “work”. Lots of things crashed in MDX 1 normally for various syntax reasons because strings were passed through. Gatsby had a rather complex system to parse those things again. Which wasn’t part of the MDX projects but their own language. That’s no longer needed in MDX 2, because MDX does all of that.
• Presumably, <SomeJSXComponent /> is just an example, but that isn’t valid HTML. That’s JSX. So if you want to type things like that, use the MDX language itself.
• It is possible to use markdown, and also to use HTML in markdown, with MDX. I don’t think it’s a smart idea though. You’re introducing another parser. A lot of work. A lot of time. Because you want to pass strings of HTML through to React. So we need to parse HTML to generate react calls so that react can build a virtual dom so that it can generate a DOM which is equivalent to the HTML. Here’s how to do it:

mdx/packages/mdx/test/compile.js

Line 768 in f77c33f

rehypePlugins: [[rehypeRaw, {passThrough: nodeTypes}]]

[ovflowd]

You only linked cli.en.md as far as I can see, the other one 404s. Which one is /api/?

Sorry, with /api/ I meant the cli.md which one is giving 404?

[ovflowd]

(I've updated my previous comments as I rushed with them 🫠)

[wooorm]

Okay, so first, your understanding of providers is incorrect.
Providers are not needed. Providers are ±10 lines of code to hook a specific React context based API into MDX.
You can swap components in without them.
You don’t need providers.
They don’t interact with parsers (they run on the client). They can’t somehow change how an HTML parser sees the XML you write.
Please read through the article on how to use MDX, which explains how to pass components, what providers are, and when you should or should not use them: https://mdxjs.com/docs/using-mdx/

Again, if I have a ### or h3 the MDXProvider will map the h3 tag to whatever I have inside the components list for h3 even for format: 'md'.

You mention two things, and there are two formats:

• In MDX, ### can be swapped out with a custom component. This works.
• In MDX, <h3> cannot be swapped out with a custom component, which is by design: type <H3> instead, you can pass a component for that (this is your NodeApiVersonLinks example, which works)
• In markdown, ### can be swapped out with a custom component. This works.
• In markdown, <h3> can be swapped out with a custom component, if you configure an HTML parser. I showed in my first comment how you can do that with one line of code.

I thought that's what MDX does by default, parsing both HTML and Markdown. Because HTML tags are not part of the MD spec...

This needs an important note: how to parse markdown, including how to parse the HTML in markdown, is defined in the markdown spec. Please see the markdown spec: https://spec.commonmark.org/0.30/. (Also see this, which I recently wrote about how the grammar has to be parsed: https://github.com/wooorm/markdown-rs/blob/main/src/construct/html_flow.rs)

The markdown spec defines a syntax that treats strings of (broken?) XML as a black box. It might be wrong! It might be right. It sees <div>? Then you have to output that.
Which is fine if you compile to a string of HTML.
Which is not what this project does.

If that's the case, I know you mentioned there's a way to do what I want, but if this is hacky or costly way (performance/memory) then I prefer not doing it and searc for another way 😅

Well. You show an MDX file. That includes <SomeJSXComponent />. Just call your file .mdx and it works.

If you actually had HTML, then what I show works, albeit slow. But <SomeJSXComponent /> is not HTML (in the way you intend it, because it’s not closed and runs very far into the future). If you want HTML, you should use custom elements (with a -, so: <some-custom-element />), and you must close them: <some-custom-element></some-custom-element>.

[ovflowd]

Please read through the article on how to use MDX, which explains how to pass components, what providers are, and when you should or should not use them: https://mdxjs.com/docs/using-mdx/

Oh boii! I had such an erroneous understanding of how MDX works! All based on assumptions made on how Gatsby was doing things 🤦

You mention two things, and there are two formats:

That is enlightening, thank you!

This needs an important note: how to parse markdown, including how to parse the HTML in markdown, is defined in the markdown spec. Please see the markdown spec: https://spec.commonmark.org/0.30/. (Also see this, which I recently wrote about how the grammar has to be parsed: https://github.com/wooorm/markdown-rs/blob/main/src/construct/html_flow.rs)

Thank you for pointing me out to these files :)

Well. You show an MDX file. That includes . Just call your file .mdx and it works.

That would work if it wasn't by the case that many parts of the file have non-complying Markdown syntax 😅 (I'm going to make a PR within nodejs.org to fix all the issues MDX was complaining about)

If you actually had HTML, then what I show works, albeit slow. But is not HTML (in the way you intend it, because it’s not closed and runs very far into the future). If you want HTML, you should use custom elements (with a -, so: ), and you must close them: .

Not going to, I simply made the /en/docs/index.md as index.mdx and fixed the issues that were non-JSX conforming.

This whole discussion was enlightening. Just a note, I don't want to break the pattern/standard, just trying to understand exactly how MDX works for each thing, so I can understand better what to expect.

Thank you, Titus! 💖

[wooorm]

Cool, no worries, feel free to ask questions! Good luck :)