docs: rewrite some docs for mdx v2

project-words.txt

@@ -18,6 +18,7 @@ autoconverted
 autogen
 autogenerating
 autohide
+autolinks
 backport
 backticks
 bartosz
@@ -48,6 +49,7 @@ codegen
 codeql
 codesandbox
 codespaces
+commonmark
 contravariance
 corejs
 crawlable

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

@@ -18,7 +18,7 @@ And the answer is: create an MDX plugin! MDX has a built-in [plugin system](http
 - Creating remark/rehype plugins to transform the elements generated by existing MDX syntax;
 - Creating remark/rehype plugins to introduce new syntaxes to MDX.
 
-If you play with the [MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground), you would notice that the MDX transpilation has two intermediate steps: Markdown AST (MDAST), and Hypertext AST (HAST), before arriving at the final JSX output. MDX plugins also come in two forms:
+If you play with the [MDX playground](https://mdxjs.com/playground/), you would notice that the MDX transpilation has two intermediate steps: Markdown AST (MDAST), and Hypertext AST (HAST), before arriving at the final JSX output. MDX plugins also come in two forms:
 
 - **[Remark](https://github.com/remarkjs/remark/)**: processes the Markdown AST.
 - **[Rehype](https://github.com/rehypejs/rehype/)**: processes the Hypertext AST.
@@ -45,15 +45,9 @@ These are all typical use-cases of Remark plugins, which can also be a source of
 An MDX plugin is usually an npm package, so you install them like other npm packages using npm. Take the [math plugins](./markdown-features-math-equations.mdx) as an example.
 
 ```bash npm2yarn
-npm install --save remark-math@3 rehype-katex@4
+npm install --save remark-math@5 rehype-katex@6
 ```
 
-:::note
-
-There's recently a trend in the Remark/Rehype ecosystem to migrate to ES Modules, a new JavaScript module system, which Docusaurus doesn't support yet. Please make sure your installed plugin version is CommonJS-compatible before we officially support ESM. Alternatively, you can read about using dynamic `import()` as a workaround in the tutorial of installing [`rehype-katex`](./markdown-features-math-equations.mdx#upgrading-rehype-katex-beyond-recommended-version).
-
-:::
-
 <details>
   <summary>How are <code>remark-math</code> and <code>rehype-katex</code> different?</summary>
 
@@ -63,30 +57,34 @@ Next, the `rehype-katex` operates on the Hypertext AST where everything has been
 
 </details>
 
-Next, add them to the plugin options through plugin or preset config in `docusaurus.config.js`:
+:::caution
+
+Many official Remark/Rehype plugins are using ES Modules, a new JavaScript module system, which Docusaurus doesn't support yet. To work around this issue, we recommend to use dynamic `import()` inside an `async` config creation function.
+
+:::
+
+Next, add them to the plugin options through plugin or preset config in `docusaurus.config.js`, using dynamic `import()`:
 
 ```js title="docusaurus.config.js"
 // highlight-start
-const math = require('remark-math');
-const katex = require('rehype-katex');
-// highlight-end
-
-module.exports = {
-  title: 'Docusaurus',
-  tagline: 'Build optimized websites quickly, focus on your content',
-  presets: [
-    [
-      '@docusaurus/preset-classic',
-      {
-        docs: {
-          // highlight-start
-          remarkPlugins: [math],
-          rehypePlugins: [katex],
-          // highlight-end
+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
+          },
         },
-      },
+      ],
     ],
-  ],
+  };
 };
 ```
 
@@ -95,21 +93,23 @@ module.exports = {
 Some plugins can be configured and accept their own options. In that case, use the `[plugin, pluginOptions]` syntax, like this:
 
 ```js title="docusaurus.config.js"
-module.exports = {
-  presets: [
-    [
-      '@docusaurus/preset-classic',
-      {
-        docs: {
-          remarkPlugins: [math],
-          rehypePlugins: [
-            // highlight-next-line
-            [katex, {strict: false}],
-          ],
+module.exports = async function createConfigAsync() {
+  return {
+    presets: [
+      [
+        '@docusaurus/preset-classic',
+        {
+          docs: {
+            rehypePlugins: [
+              // highlight-start
+              [(await import('rehype-katex')).default, {strict: false}],
+              // highlight-end
+            ],
+          },
         },
-      },
+      ],
     ],
-  ],
+  };
 };
 ```