Better compatibility with CommonMark

Subject of the feature

Sometimes the content that people write using markdown should be compatible with external markdown-related tools (github markdown, markdownlint…) that do not rely on MDX. Having better compatibility with CommonMark ecosystem would be nice.

Problem

https://daringfireball.net/projects/markdown/syntax#html

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

https://mdxjs.com/getting-started#markdown

MDX supports standard Markdown syntax

The MDX doc statement is not totally true:

• <span style="color: red">Hello</span> => parse error in MDX
• <span style={{ color: 'red' }}>Hello</span> => renders strangely on CommonMark systems

Not being compatible with CommonMark means that if you need a source file to display correctly in MDX env + CommonMark env, you don’t always have a solution.

Expected behavior

That would be nice if MDX was more compatible with existing markdown ecosystem, or highlighted more clearly how it currently diverges, and what are the end goals regarding compatibility.

Alternatives

Wondering if MDX could try to convert html tags to jsx as a compilation step? (for example using https://transform.tools/html-to-jsx)

Wondering if MDX could offer some kind of “compatibility mode”. I work on Docusaurus v2, and some of our users don’t really care about using React components in markdown, they just want to use regular markdown. It would be very nice if we could support 2 modes (one enabling embedding React comps, the other being regular markdown), keeping MDX as the only markdown compiler, and without having to duplicate the work (we rely heavily on things like MDXProvider currently).

Wondering if it could be possible to escape regular html syntax with some custom tag or whatever, so that we could embed React comps in a MD doc, yet also be able to use html syntax at the same time.

---

Related discussion on our repo: https://github.com/facebook/docusaurus/discussions/3009

Our v1 -> v2 migration guide (from CommonMark to MDX) ask users to perform some markdown changes to make it compatible with MDX. That could be nice if it didn’t require any change. https://v2.docusaurus.io/docs/next/migrating-from-v1-to-v2#update-markdown-syntax-to-be-mdx-compatible

[wooorm]

I’ll explore using https://github.com/rexxars/react-markdown

Why not look at the stuff that react-markdown and mdx are using under the hood? unified. As react-markdown hasn’t been updated in a while. Mapping HTML names to components is possible.

And I’d suggest using extensions: .md and .mdx.

[wooorm]

I think so yeah. And: I’d personally like to make the two more similar but that’ll take some iterations. Feel free to ask me more Qs tho!