Refactor Markdown, MDX and CommonMark docs

packages/docusaurus-types/src/config.d.ts

@@ -16,6 +16,17 @@ export type ThemeConfig = {
   [key: string]: unknown;
 };
 
+export type MarkdownPreprocessor = (args: {
+  filePath: string;
+  fileContent: string;
+}) => string;
+
+export type MDX1CompatOptions = {
+  comments: boolean;
+  admonitions: boolean;
+  headingIds: boolean;
+};
+
 export type MarkdownConfig = {
   /**
    * The Markdown format to use by default.
@@ -51,17 +62,13 @@ export type MarkdownConfig = {
    *
    * @param args
    */
-  preprocessor?: (args: {filePath: string; fileContent: string}) => string;
+  preprocessor?: MarkdownPreprocessor;
 
   /**
    * Set of flags make it easier to upgrade from MDX 1 to MDX 2
    * See also https://github.com/facebook/docusaurus/issues/4029
    */
-  mdx1Compat: {
-    comments: boolean;
-    admonitions: boolean;
-    headingIds: boolean;
-  };
+  mdx1Compat: MDX1CompatOptions;
 };
 
 /**

website/docs/api/docusaurus.config.js.mdx

@@ -4,6 +4,8 @@ description: API reference for Docusaurus configuration file.
 slug: /api/docusaurus-config
 ---
 
+import APITable from '@site/src/components/APITable';
+
 # `docusaurus.config.js`
 
 :::info
@@ -400,8 +402,24 @@ The global Docusaurus Markdown config.
 - Type: `MarkdownConfig`
 
 ```ts
+type MarkdownPreprocessor = (args: {
+  filePath: string;
+  fileContent: string;
+}) => string;
+
+type MDX1CompatOptions =
+  | boolean
+  | {
+      comments: boolean;
+      admonitions: boolean;
+      headingIds: boolean;
+    };
+
 type MarkdownConfig = {
+  format: 'mdx' | 'md' | 'detect';
   mermaid: boolean;
+  preprocessor?: MarkdownPreprocessor;
+  mdx1Compat: MDX1CompatOptions;
 };
 ```
 
@@ -410,12 +428,34 @@ Example:
 ```js title="docusaurus.config.js"
 module.exports = {
   markdown: {
+    format: 'mdx',
     mermaid: true,
+    preprocessor: ({filePath, fileContent}) => {
+      return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
+    },
+    mdx1Compat: {
+      comments: true,
+      admonitions: true,
+      headingIds: true,
+    },
   },
 };
 ```
 
-- `mermaid`: when `true`, allows Docusaurus to render Markdown code blocks with `mermaid` language as Mermaid diagrams.
+```mdx-code-block
+<APITable>
+```
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `format` | `'mdx' \| 'md' \| 'detect'` | `'mdx'` | The default parser format to use for Markdown content. Using 'detect' will select the appropriate format automatically based on file extensions: `.md` vs `.mdx`. |
+| `mermaid` | `boolean` | `false` | When `true`, allows Docusaurus to render Markdown code blocks with `mermaid` language as Mermaid diagrams. |
+| `preprocessor` | `MarkdownPreprocessor` | `undefined` | Gives you the ability to alter the Markdown content string before parsing. Use it as a last-resort escape hatch or workaround: it is almost always better to implement a Remark/Rehype plugin. |
+| `mdx1Compat` | `MDX1CompatOptions` | `{comments: true, admonitions: true, headingIds: true}` | Compatibility options to make it easier to upgrade to Docusaurus v3+. See the [MDX 2 PR for details](https://github.com/facebook/docusaurus/pull/8288). |
+
+```mdx-code-block
+</APITable>
+```
 
 ### `customFields` {#customFields}
 

website/docs/guides/markdown-features/markdown-features-intro.mdx

@@ -8,22 +8,54 @@ slug: /markdown-features
 
 import BrowserWindow from '@site/src/components/BrowserWindow';
 
-Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible.
+Docusaurus uses **[Markdown](https://commonmark.org/)** as its main content authoring format.
 
-Docusaurus 2 uses modern tooling to help you compose your interactive documentation with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.
+:::tip Learn Markdown
 
-:::important
+You can [learn Markdown in 10 minutes](https://commonmark.org/help/).
 
-This section assumes you are using the official Docusaurus content plugins.
+:::
+
+Docusaurus uses modern tooling to help you create **interactive documentation**.
+
+The **[MDX](https://mdxjs.com/)** compiler transforms **Markdown files to React components**, and allows you to use JSX in your Markdown content. This enables you to easily interleave React components within your content, and create delightful learning experiences.
+
+:::tip Use the MDX Playground
+
+The **[MDX playground](https://mdxjs.com/playground/)** is your new best friend!
+
+It is a very helpful debugging tool that shows how the MDX compiler transforms Markdown to React.
+
+**Options**: select the right format (MDX or CommonMark) and the following plugins Docusaurus uses: `remark-gfm`, `remark-directive`, `rehype-raw`.
+
+:::
+
+## MDX vs. CommonMark {#mdx-vs-commonmark}
+
+Docusaurus compiles both `.md` and `.mdx` files to React components using the MDX compiler, but **the syntax can be interpreted differently** depending on your settings.
+
+The MDX compiler supports [2 formats](https://mdxjs.com/packages/mdx/#optionsformat):
+
+- The [MDX format](https://mdxjs.com/docs/what-is-mdx/): a powerful parser allowing the usage of JSX
+- The [CommonMark format](https://commonmark.org/): a standard-compliant Markdown parser that does not allow the usage of JSX
+
+By default, **Docusaurus v3 uses the MDX format for all files** (including `.md` files) for historical reasons.
+
+It is possible to **opt-in for CommonMark** using the [`siteConfig.markdown.format`](../../api/docusaurus.config.js.mdx#markdown) setting or the `format: md` front matter.
+
+:::tip how to use CommonMark
+
+If you plan to use CommonMark, we recommend the [`siteConfig.markdown.format: 'detect'`](../../api/docusaurus.config.js.mdx#markdown) setting. The appropriate format will be selected automatically, based on file extensions:
+
+- `.md` files will use the CommonMark format
+- `.mdx` files will use the MDX format
 
 :::
 
 ## Standard features {#standard-features}
 
 Markdown is a syntax that enables you to write formatted content in a readable syntax.
 
-We use [MDX](https://mdxjs.com/) as the parsing engine, which can do much more than just parsing [standard Markdown syntax](https://daringfireball.net/projects/markdown/syntax), like rendering React components inside your documents as well.
-
 ```md
 ### My Doc Section
 
@@ -143,9 +175,3 @@ Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/
 
 </BrowserWindow>
 ```
-
-:::note
-
-In practice, those are not really HTML elements, but React JSX elements, which we'll cover next!
-
-:::

website/docs/guides/markdown-features/markdown-features-react.mdx

@@ -13,24 +13,9 @@ import TabItem from '@theme/TabItem';
 import styles from './markdown-features-react.module.css';
 ```
 
-## Using JSX in Markdown {#using-jsx-in-markdown}
-
 Docusaurus has built-in support for [MDX v2](https://mdxjs.com/), which allows you to write JSX within your Markdown files and render them as React components.
 
-:::info MDX vs. CommonMark
-
-Docusaurus parses both `.md` and `.mdx` files using MDX, but **the syntax is interpreted differently based on the file extension**:
-
-- With the `.md` extension, the parser is compatible with [CommonMark](https://commonmark.org/) and does not allow the usage of JSX.
-- With the `.mdx` extension, the parser is stricter than [CommonMark](https://commonmark.org/) and is not 100% compatible with it, but it becomes possible to use JSX.
-
-It is also possible to override the file extension format with front matter: `format: mdx`.
-
-The rest of this page assumes usage of the `mdx` format.
-
-:::
-
-Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX.
+Check out the [MDX docs](https://mdxjs.com/) to see what fancy stuff you can do with MDX.
 
 :::tip Debugging MDX