feat(mdx): add siteConfig.markdown.format to configure the default content parser (MDX / CommonMark)

[slorber]

Motivation

Add a new siteConfig.markdown.format option.

• Completes the MDX v2 upgrade PR: feat: upgrade to MDX v2 #8288
• Address comment: RFC: CommonMark compatibility, supporting multiple markdown/content parsers #3018 (comment)
• Closer to what Docusaurus v2 is doing: use mdx by default but allow opt-in for CommonMark
• frontMatter.mdx.format wins over siteConfig.markdown.format

Site config API:

const siteConfig = {
  markdown: {
    format: "mdx"
  }
};

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:

• https://deploy-preview-9097--docusaurus-2.netlify.app/tests/pages/markdown-tests-md/
• https://deploy-preview-9097--docusaurus-2.netlify.app/tests/pages/markdown-tests-mdx/

[netlify]

✅ [V2]

Name	Link
🔨 Latest commit	c396566
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/6495bfd42ab62f0008ec275f
😎 Deploy Preview	https://deploy-preview-9097--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 80	🟢 97	🟢 92	🟢 100	🟠 89	Report
/docs/installation	🟠 71	🟢 100	🟢 92	🟢 100	🟠 89	Report

[github-actions]

Size Change: +42 B (0%)

Total Size: 1.1 MB

Filename	Size	Change
website/build/assets/js/main.********.js	828 kB	+42 B (0%)

ℹ️ View Unchanged

Filename	Size
website/.docusaurus/globalData.json	117 kB
website/build/assets/css/styles.********.css	113 kB
website/build/index.html	41 kB

_{compressed-size-action}