💥 Proposal

People using Docusaurus don't always like the MDX parser:

• If you come from an existing Markdown docs base (like v1), you need to make it compatible with MDX, despite that you actually don't plan to embed any JSX components in the markdown
• You might want to keep compatibility to CommonMark, to stay compatible with existing ecosystem (Github md viewer, markdownlint etc...)
• It creates more "lock-in", because to leave MDX you have to convert back to CommonMark
• It can be confusing to not be able to use CommonMark (ie html tags, not jsx) in .md files, and to learn that even .md files are parsed with MDX

Related discussions:

• How to use plain Markdown (CommonMark) in Docusaurus v2? #3009
• Better compatibility with CommonMark mdx-js/mdx#1125

Solution ?

• https://github.com/rexxars/react-markdown
• https://github.com/probablyup/markdown-to-jsx

These libs:

• is also based on UnifiedJS ecosystem
• allows to pass custom React elements to replace existing tags

We may be able to build some shared abstraction on top of react-markdown + MDX.

If this works, we could switch from one parser to another with a simple switch/setting, that could be:

• .md -> common-mark compatible parser
• .mdx -> MDX
• global default D2 parser setting
• parser frontmatter

The idea would be that, if a doc does not embed any html/jsx, we could switch from one parser to the other, and shouldn't notice any change.

--

Feedbacks welcome