[Guider] Certain HTML elements throw errors on rerenders

[jonbarrow]

Making an official issue for this, as it was only previously discussed via Discord.

When using raw HTML elements in the mdx files, the page throws many errors when hot reloading. Using raw HTML elements is required in situations like making an element with a custom ID for a link.

Additionally, heading elements do not get any of their styles applied to them.

Errors example:

Unstyled headers example:

[mrjvs]

Can't reproduce hydration errors, this just works:

Can you give a reproducable example?

[jonbarrow]

Can you give a reproducable example?

<h2 id="hello-world">Coolio</h2>
test

It needs to have other content in the page as well. It also looks like it has something to do with putting it on one line?

If I have it formatted on multiple lines like yours, it works regardless of content.

If it's on one line then it only works if there's no other page content. If there's extra content on the page, it throws the error.

You may also need to try saving, modifying, and resaving the file to trigger a rebuild.

Also is it normal for HTML in mdx to not be as flexible as it usually would be? For example the following

<h2 id="hello-world">Coolio
</h2>
test

Throws a compilation error, but is valid HTML and other markdown parsers accept it

[mrjvs]

Seems like its a side-effect of how markdown is parsed.

When markdown sees this:

Line 1
Line 2

It will parse it as one line:

<p>Line 1 Line 2</p>

---

When markdown sees this:

<span>line 1</span>
line 2

It will become this:

<p><span>line 1</span> line 2</p>

---

And finally when you use a heading like this:

<h2>Line 1</h2>
line 2

It will become this:

<p><h2>Line 1</h2> line 2</p>

Which is a problem since its invalid html, and the browser will correct it to <h2>Line 1</h2><p>line 2</p> which suddenly doesn't match what react and the dev server expects to be. Thus causing a hydration error.

I'll be honest, not sure how to fix it and if I should even try to. (since its easily fixable by user by just adding a extra newline inbetween)

[jonbarrow]

That seems like an issue with the parser you're using then? I just checked the resulting html from GitHubs parser used in gists and it produces expected results. The heading and content are rendered separately

the browser will correct it to <h2>Line 1</h2><p>line 2</p>

Unless dev tools is showing different html than what is actually being used, this doesn't seem to the case? There doesn't seem to be any correction happening on the browser side afaict?

[jonbarrow]

I'll be honest, not sure how to fix it and if I should even try to. (since its easily fixable by user by just adding a extra newline inbetween)

Tbh the biggest issue is just the lack of clarity on what the issue actually is, even if you don't intend to fix it. It's not clear that this is what's causing the error, and it's not mentioned in the docs, so I can see someone (like myself) stumbling into this because

• Using standard html in markdown is super common
• It works with regular html
• It works with other markdown parsers

and not understanding what the issue is, because the error isn't super clear. I'm not sure if there's any way to improve the error though

[mrjvs]

I think ill just mention it a few times in the documentation and add a troubleshooting section.

I don't think I can change the error, it's pretty deep into nextjs.

[jonbarrow]

So long as it's mentioned well in the docs that should be fine. My concern honestly wasn't fixing this specific issue after you explained it (I know it's hard to fix and kinda out of your hands), my concern was people stumbling into this as it's a REALLY common thing to do and blaming the library

[mrjvs]

Yea I agree, ive ran into it myself a few times since this issue.

MDX does seem to be aware of it, it explicitly says it makes invalid html on this page: https://mdxjs.com/docs/what-is-mdx/#interleaving

Their stance is that it's a downside of the concept of mdx and they don't plan on changing internals to fix it. It'd be really hard to do that on their end anyway, since any jsx component can be either inline or a block, even standard html elements in jsx can technically be something completely different. They can't assume anything.

[jonbarrow]

That's very fair, nice to see there's a clear page to link to about this as well. It's unfortunate but I understand the reasoning