Do not force .md to use CommonMark until the MDX Extension for VSCode is improved
closed
S
Shannon Greywalker
VSCode is a highly popular IDE for working with Markdown files in Docusaurus repos. However, .mdx files are not natively supported by VSCode, and you're required to install the 3rd party, open source MDX Extension to support working with .mdx files in VSCode. A significant issue as of this datestamp (7-Nov-2024) is that the MDX Extension for VSCode doesn't support IntelliSense link path completion for # and ## triggers in .mdx files. This means that a critical everyday authoring task for your front-line technical writers -- creating links within and among all the topics in your docsite -- is greatly crippled if you force your front-line tech writers to work ONLY with .mdx files.
I've raised an issue for this at mdx-analyzer: https://github.com/mdx-js/mdx-analyzer/issues/482
I've also raised a discussion for this at mdx-js: https://github.com/orgs/mdx-js/discussions/2557
However, since mdx-js and mdx-analyzer are OSS repos, it's anyone's guess when they will be able to prioritize fixing this problem. Perhaps one lever that the Docusaurus team can apply is evidenced in the discussion at mdx-js: they do seem to be open to PRs from anyone with the capability to fix this issue.
Activity Feed
Sort by
Joshua Chen
closed
Joshua Chen
I believe that by default both
.mdx
and .md
are MDX unless you explicitly use siteConfig.markdown.format: "detect"
. Is that not the case?S
Shannon Greywalker
Joshua Chen
The problem isn't with Docsaurus itself, nor how Docusarus renders an .md file. Yes, by default Docusaurus renders .md files with the MDX parser.
The problem I'm describing in the OP relates to a very common and popular workflow in the toolchain for Docusaurus: using VSCode to create and edit those .md and .mdx files.
VSCode does not natively support .mdx files. So you're forced to load the 3rd party "MDX Extension" maintained by an open-source vendor to enable VSCode to understand .mdx files. Which is fine, in theory, except that the "MDX Extension" does NOT currently (and correctly) support IntelliSense link path completion.
Creating and checking links is an integral and pervasive aspect of authoring documentation topics. A _huge_ benefit to VSCode as your primary editor in the toolchain is its robust and excellent IntelliSense link path completion, and its robust automated link validation.
Therefore, put all this together and the MDX Extension for VSCode is a huge limiting factor on being able to author .mdx files quickly and easily with minimal errors and fast IntelliSense autocomplete for finding the target files for links. Therefore, it's much faster and easier and safer to work with .md files, because VSCode natively supports .md files with all the nice bells and whistles.
This is ultimately a problem for the MDX open source "team" to solve, but it has a downstream chilling effect on some requests I've seen made to Docusaurus recently to "Force Docusaurus to use CommonMark parser for .md files". I don't want that, because doing so would force me to use .mdx files to get the MDX rendering behavior I want
in Docusaurus
, and that would mess my team up since we all use VSCode to actually work with our Docusarus files.Joshua Chen
Shannon Greywalker We are unlikely to change this default soon, since all .md files have been MDX since day 1 of Docusaurus 2. Different people come with different expectations of what .md should mean and it is impossible for us to satisfy everyone, which is why this configuration is there in the first place. I understand your request and I sympathize with it, and yes we will continue to do it the way you like. If you sent this in response to the other request, rest assured that your voice is already heard as we consider the other thread, and there's no need to send a new one.