RFC: MDX comment syntax

[johno]

As part of #1039 comment syntax currently only supports JS comment expressions:

# Hello, world!

{/* I am a comment */}

This syntax is nice because it feels more JSX-y than HTML comments. However, it comes at a cost of interoperability with Markdown (which uses HTML comments).

I'm inclined to think ensuring that we also support HTML comments (despite it being a bit precarious to have multiple syntaxes) is worth it so that your average Markdown/README file works with MDX out of the box.

# Hello, world!

{/* I'm a comment */}
<!-- I'm a comment, too! -->

Anyone have any thoughts or opinions here?

[ChristopherBiscardi]

I agree

[wooorm]

While adding support isn’t very technically complex, I’m relatively strongly against, because it adds mental complexity. MDX already “comes at a cost of interoperability with Markdown”, namely: HTML isn’t supported, and you get JSX in return. I don’t think there should be exceptions to that rule, as those will make it harder to reason about or explain what the language is. JSX is HTML but stricter; being strict is expected.

[laurieontech]

I wouldn't break something that currently works in v1 without a need to do so. That being said, the fuzzy line of markdown interoperability is not ideal.

[jescalan]

Agreed with the original post, feels like supporting html comments is pretty important, even if actually using them is discouraged.

EDIT: I have changed my mind on this, and do think that html comments should not be supported. They are not supported by jsx, which mdx compiles to. Currently, html comments "work" but are silently removed from the output, which means that they don't actually work. Since jsx as an output format doesn't support html comments, I see no reason to allow them with mdx, which is a superset of jsx. It would be trivial to release a codemod along with mdx v2 that converts html comments into jsx comments, which are valid jsx and also behave as expected -- showing up in development but being removed from the final output.

[JounQin]

It seems that would break remark-lint's disable comment?

[wooorm]

Hmm, indeed.
It would be possible to support comments like this though {/* lint ignore this */}