diff --git a/packages/docusaurus-mdx-loader/README.md b/packages/docusaurus-mdx-loader/README.md
index 92a22ca6d8..b3a60699a6 100644
--- a/packages/docusaurus-mdx-loader/README.md
+++ b/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,
+  },
+};
+```
diff --git a/packages/docusaurus-mdx-loader/src/loader.ts b/packages/docusaurus-mdx-loader/src/loader.ts
index 12ac0e192f..fee2920a2e 100644
--- a/packages/docusaurus-mdx-loader/src/loader.ts
+++ b/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,
         {
diff --git a/website/docs/api/docusaurus.config.js.md b/website/docs/api/docusaurus.config.js.md
index 2b42d82b6f..87a4525e0a 100644
--- a/website/docs/api/docusaurus.config.js.md
+++ b/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`.