feat(mdx): add siteConfig.markdown.format to configure the default content parser (MDX / CommonMark) #9097
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation
Add a new
siteConfig.markdown.format
option.mdx
by default but allow opt-in for CommonMarkfrontMatter.format
wins oversiteConfig.markdown.format
Site config API:
This gives global control over the default parsing format used by MDX:
https://mdxjs.com/packages/mdx/#optionsformat
Possible values:
mdx
(default): parse all Markdown files as MDX (JSX)md
: parse all Markdown files as CommonMark (no JSX)detect
: parse Markdown files as MDX or CommonMark according to file extension (.mdx
vs.md
)Note: all 3 values are also possible to use as front matter like
format: md
, and front matter takes precedence over the site global markdown format setting.In Docusaurus v3 the default setting is
mdx
because historically Docusaurus v2 used to parse everything as MDX: let's keep this behavior for now to make the upgrade easier.In Docusaurus v4 we will likely switch to
detect
as a breaking chance, making it easier for CommonMark sites adopt Docusaurus without having to even know about this setting.Test Plan
Unit tests + dogfood + preview
Test links
Our website uses
format: 'detect'
, as a way to dogfood the CommonMark support: