How to use plain Markdown (CommonMark) in Docusaurus v2?

[borekb]

I really like Docusaurus v2 and would like to use it for our docs site but we need to use standard Markdown, not MDX. Is there a way to swap the parser somehow?

---

As a side note, I was quite surprised to learn about this detail relatively deep in the docs (here). I was expecting that Docusaurus would support Markdown easily, as it's one of the main claims on the homepage and there are a lot of docs/**/*.md files everywhere, but so far I haven't figured out how to do it. Note sure if I have to mention this or not but MDX is not Markdown – it is JSX written differently, allowing Markdown syntax in some specific places. You generally cannot send Markdown documents to it, some constructs will throw a parse error in MDX.

---

🏁 Summary: We discussed this below and in the JSX project itself (mdx-js/mdx#1125), eventually leading to RFC: CommonMark compatibility, supporting multiple markdown parsers #3018

[slorber]

Hi,

https://mdxjs.com/getting-started#markdown says MDX supports standard Markdown syntax

If you think features are missing in MDX, I think it's a bug to open on their repo, as clearly their intention is to support standard markdown.

Not sure they mention commonmark in their doc, but it's mentionned in the issues: https://github.com/mdx-js/mdx/search?q=CommonMark&type=Issues

As a side note, I was quite surprised to learn about this detail relatively deep in the docs (here).

Yes, the v2 is alpha, and the doc can still be improved a lot, don't hesitate to contribute and submit a PR.

Is there a way to swap the parser somehow?

Each plugin implements the MD-based system of its choice, that's also a reason why this is under the Docs section, and not more "global". It is possible for you to fork the existing docs plugin based on MDX, and publish a non-MDX version of it.

Note sure if I have to mention this or not but MDX is not Markdown

What is markdown anyway? Does it specify how exactly the file has to be rendered to the end user? I don't think this is something what matters much, it's an implementation detail you should not have to care about.

it is JSX written differently, allowing Markdown syntax in some specific places.

To me that's more the opposite: the doc is plain markdown with interleaved JSX. I agree that it compiles the markdown to JSX in the end but it's an implementation detail.

---

You generally cannot send Markdown documents to it, some constructs will throw a parse error in MDX.

We come to the most interesting part.

So the main info we need for resolving this issue is: what constructs exactly do you need that are in Markdown, but don't work with MDX exactly?

Is MDX really the problem? If they allowed the missing syntax that does not work currently? That's worth seeing if it's in their plans.

If you can give us an exhaustive list of things from common marks that don't work but should work, that would definitively help.

Also, how costly is it for you to modify a bit the existing markdown to make it work with current version of MDX? In our experience most v1 Docusaurus sites are able to migrate to v2 with only minor changes. Do you have another usecase for which updating the MD would be more annoying?

[slorber]

Hi

I understand where you come from.

Unfortunately all the features of the docs plugin and the classic theme are built around this special MDX markdown parser that enable us to write custom React elements for things like code blocks etc... It is possible to replace it and provide your own plugins/themes, but it would be a lot of work and probably not worth it.

Even in our v1-v2 migration guide, we recommend users to adapt the markdown syntax: https://v2.docusaurus.io/docs/next/migrating-from-v1-to-v2#update-markdown-syntax-to-be-mdx-compatible

What I'd do is explore if there's not a way to automate your workflow by using a tool to convert markdown to mdx automatically, probably based on some existing tooling like https://transform.tools/html-to-jsx

This way you could keep your source files in commonmark and copy the files to docusaurus when needed only?

I've opened an issue on MDX to see what they think of this problem: mdx-js/mdx#1125

[borekb]

Thanks a lot, that issue is well-articulated and it also explained nicely how Docusaurus v2 depends on MDX heavily.

To expand on our use case, this is probably the ideal end state:

• When the file is .md, it is treated as CommonMark + some common extensions like tables, strikethroughs etc.
• When the file is .mdx, it is MDX.

Thanks again for raising the issue in the upstream project.

[borekb]

After some useful discussion in mdx-js/mdx#1125, I think it's back to Docusaurus since it's pretty clear that MDX will not support CommonMark anytime soon. I'm saying that especially because of a recently merged PR mdx-js/mdx#1039 which further diverges from CommonMark, e.g., these will no longer work in MDX v2:

🚫 will not work in MDX v2:

<!-- more -->

🚫 will not work in MDX v2:

Here's a code example:

    console.log(1)

🚫 will not work in MDX v2:

See <https://example.com> for more information

I think Docusaurus could run .md files through some standard CommonMark parser and then internally convert them to MDX if it needs to do that. (I don't have any understanding why Docusaurus needs MDXProvider for plain Markdown files in the first place but I'm assuming there is some internal motivation.)

On a related note, React Styleguidist has a simple approach on how to do live playgrounds from plain MD files. I'm just mentioning it to show that MDX is not the only way to get interactivity into the docs site.

[slorber]

Thanks @borekb

I've opened a RFC here: #3018

However, we are focusing on v2 missing/blocking features like versioning / i18n, so it's unlikely we work on this very soon, as it could be a lot of work, and most users are currently fine with MDX

[borekb]

Thanks a lot, I'll mark this question as answered.