From 22b7c8c8bfedd0995a0cbb93f73fd0f08428ab67 Mon Sep 17 00:00:00 2001
From: sebastienlorber <lorber.sebastien@gmail.com>
Date: Sat, 14 Oct 2023 01:58:20 +0200
Subject: [PATCH] refactor mdx plugin docs

---
 .../markdown-features-math-equations.mdx      | 121 ++++++++++++------
 .../markdown-features-plugins.mdx             |   4 +-
 2 files changed, 83 insertions(+), 42 deletions(-)

diff --git a/website/docs/guides/markdown-features/markdown-features-math-equations.mdx b/website/docs/guides/markdown-features/markdown-features-math-equations.mdx
index 545bfdb1be91..8fd3235148a6 100644
--- a/website/docs/guides/markdown-features/markdown-features-math-equations.mdx
+++ b/website/docs/guides/markdown-features/markdown-features-math-equations.mdx
@@ -63,25 +63,63 @@ Make sure to use `remark-math >= 5` and `rehype-katex >= 6` for Docusaurus v3 (u
 
 :::
 
-Those 2 plugins are now only available as ESM packages, and you will need to import them dynamically.
+Those 2 plugins are now [**only available as ES Modules**](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). To simplify usage, it is recommended to use an [**ES Modules**](https://flaviocopes.com/es-modules/) config file:
 
-First, turn your site config into an async config creator function:
+```js title="ES module docusaurus.config.js"
+// highlight-start
+import remarkMath from 'remark-math';
+import rehypeKatex from 'rehype-katex';
+// highlight-end
 
-```js title="docusaurus.config.js"
-export default async function createConfigAsync() {
-  return {
-    // your site config...
-  };
-}
+// highlight-start
+export default {
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          path: 'docs',
+          // highlight-start
+          remarkPlugins: [remarkMath],
+          rehypePlugins: [rehypeKatex],
+          // highlight-end
+        },
+      },
+    ],
+  ],
+};
 ```
 
-It is now possible to import the plugins dynamically and add them to your content plugin or preset options (usually `@docusaurus/preset-classic` docs options):
+<details>
+    <summary>Using a [**CommonJS**](https://nodejs.org/api/modules.html#modules-commonjs-modules) config file?</summary>
 
-```js
-remarkPlugins: [(await import('remark-math')).default],
-rehypePlugins: [(await import('rehype-katex')).default],
+    If you decide to use a CommonJS config file, it is possible to load those ES module plugins thanks to dynamic imports and an async config creator function:
+
+```js title="CommonJS module docusaurus.config.js"
+// highlight-start
+module.exports = async function createConfigAsync() {
+  // highlight-end
+  return {
+    presets: [
+      [
+        '@docusaurus/preset-classic',
+        {
+          docs: {
+            path: 'docs',
+            // highlight-start
+            remarkPlugins: [(await import('remark-math')).default],
+            rehypePlugins: [(await import('rehype-katex')).default],
+            // highlight-end
+          },
+        },
+      ],
+    ],
+  };
+};
 ```
 
+</details>
+
 Include the KaTeX CSS in your config under `stylesheets`:
 
 ```js
@@ -99,37 +137,40 @@ stylesheets: [
 Overall the changes look like:
 
 ```js title="docusaurus.config.js"
-export default async function createConfigAsync() {
-  return {
-    title: 'Docusaurus',
-    tagline: 'Build optimized websites quickly, focus on your content',
-    presets: [
-      [
-        '@docusaurus/preset-classic',
-        {
-          docs: {
-            path: 'docs',
-            // highlight-start
-            remarkPlugins: [(await import('remark-math')).default],
-            rehypePlugins: [(await import('rehype-katex')).default],
-            // highlight-end
-          },
-        },
-      ],
-    ],
-    // highlight-start
-    stylesheets: [
+// highlight-start
+import remarkMath from 'remark-math';
+import rehypeKatex from 'rehype-katex';
+// highlight-end
+
+export default {
+  title: 'Docusaurus',
+  tagline: 'Build optimized websites quickly, focus on your content',
+  presets: [
+    [
+      '@docusaurus/preset-classic',
       {
-        href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
-        type: 'text/css',
-        integrity:
-          'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
-        crossorigin: 'anonymous',
+        docs: {
+          path: 'docs',
+          // highlight-start
+          remarkPlugins: [remarkMath],
+          rehypePlugins: [rehypeKatex],
+          // highlight-end
+        },
       },
     ],
-    // highlight-end
-  };
-}
+  ],
+  // highlight-start
+  stylesheets: [
+    {
+      href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
+      type: 'text/css',
+      integrity:
+        'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
+      crossorigin: 'anonymous',
+    },
+  ],
+  // highlight-end
+};
 ```
 
 ## Self-hosting KaTeX assets {#self-hosting-katex-assets}
diff --git a/website/docs/guides/markdown-features/markdown-features-plugins.mdx b/website/docs/guides/markdown-features/markdown-features-plugins.mdx
index 6e421fcb078b..a8ffb356a727 100644
--- a/website/docs/guides/markdown-features/markdown-features-plugins.mdx
+++ b/website/docs/guides/markdown-features/markdown-features-plugins.mdx
@@ -97,7 +97,7 @@ If you decide to use a CommonJS config file, it is possible to load those ES mod
 
 ```js title="docusaurus.config.js"
 // highlight-start
-export default async function createConfigAsync() {
+module.exports = async function createConfigAsync() {
   // highlight-end
   return {
     presets: [
@@ -115,7 +115,7 @@ export default async function createConfigAsync() {
       ],
     ],
   };
-}
+};
 ```
 
 </details>