Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 4 commits into from
Jun 23, 2023

Conversation

slorber
Copy link
Collaborator

@slorber slorber commented Jun 23, 2023

Motivation

Add a new siteConfig.markdown.format option.

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:

@slorber slorber added the pr: new feature This PR adds a new API or behavior. label Jun 23, 2023
@facebook-github-bot facebook-github-bot added the CLA Signed Signed Facebook CLA label Jun 23, 2023
@netlify
Copy link

netlify bot commented Jun 23, 2023

[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...

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
Copy link

github-actions bot commented Jun 23, 2023

⚡️ 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
Copy link

github-actions bot commented Jun 23, 2023

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

@slorber slorber changed the title feat(mdx): Add markdown.format siteConfig feat(mdx): Add siteConfig.markdown.format Jun 23, 2023
@slorber slorber changed the title feat(mdx): Add siteConfig.markdown.format feat(mdx): Add siteConfig.markdown.format to configure the default content parser (MDX / CommonMark) Jun 23, 2023
@slorber slorber changed the title feat(mdx): Add siteConfig.markdown.format to configure the default content parser (MDX / CommonMark) feat(mdx): add siteConfig.markdown.format to configure the default content parser (MDX / CommonMark) Jun 23, 2023
@slorber slorber mentioned this pull request Jun 23, 2023
@slorber slorber merged commit cc6d969 into main Jun 23, 2023
@slorber slorber deleted the slorber/mdx-format-global-option branch June 23, 2023 16:15
This was referenced Oct 19, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
CLA Signed Signed Facebook CLA pr: new feature This PR adds a new API or behavior.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants