docs: document siteConfig.markdown + better mdx-loader retrocompat (#8419)

packages/docusaurus-mdx-loader/README.md

@@ -44,3 +44,16 @@ Array of remark plugins to manipulate the MDXAST
 ### `metadataPath`
 
 A function to provide the metadataPath depending on current loaded MDX path that will be exported as the MDX metadata.
+
+### `markdownConfig`
+
+The global Docusaurus Markdown config (`config.markdown`), that plugin authors should forward:
+
+```js
+const loader = {
+  loader: require.resolve('@docusaurus/mdx-loader'),
+  options: {
+    markdownConfig: siteConfig.markdown,
+  },
+};
+```

packages/docusaurus-mdx-loader/src/loader.ts

@@ -173,7 +173,7 @@ export async function mdxLoader(
       ...(reqOptions.beforeDefaultRemarkPlugins ?? []),
       ...getAdmonitionsPlugins(reqOptions.admonitions ?? false),
       ...DEFAULT_OPTIONS.remarkPlugins,
-      ...(reqOptions.markdownConfig.mermaid ? [mermaid] : []),
+      ...(reqOptions.markdownConfig?.mermaid ? [mermaid] : []),
       [
         transformImage,
         {

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

@@ -394,6 +394,30 @@ module.exports = {
 };
 ```
 
+### `markdown` {#markdown}
+
+The global Docusaurus Markdown config.
+
+- Type: `MarkdownConfig`
+
+```ts
+type MarkdownConfig = {
+  mermaid: boolean;
+};
+```
+
+Example:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  markdown: {
+    mermaid: true,
+  },
+};
+```
+
+- `mermaid`: when `true`, allows Docusaurus to render Markdown code blocks with `mermaid` language as Mermaid diagrams.
+
 ### `customFields` {#customFields}
 
 Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`.