From fb4a5fb19783af449ad1f2751c2998dfbdc8a120 Mon Sep 17 00:00:00 2001
From: Thad Guidry <thadguidry@gmail.com>
Date: Fri, 5 May 2023 18:41:50 +0800
Subject: [PATCH] docs: mention equivalent config syntaxes (#8951)

Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
---
 website/docs/api/docusaurus.config.js.mdx | 33 ++++------
 website/docs/configuration.mdx            | 77 +++++++++++++++++++++++
 2 files changed, 90 insertions(+), 20 deletions(-)

diff --git a/website/docs/api/docusaurus.config.js.mdx b/website/docs/api/docusaurus.config.js.mdx
index 9b48ecd331..d86a697b1a 100644
--- a/website/docs/api/docusaurus.config.js.mdx
+++ b/website/docs/api/docusaurus.config.js.mdx
@@ -16,40 +16,33 @@ Refer to the Getting Started [**Configuration**](docs/configuration.mdx) for exa
 
 `docusaurus.config.js` contains configurations for your site and is placed in the root directory of your site.
 
-It usually exports a site configuration object:
+This file is run in Node.js using the [**CommonJS**](https://flaviocopes.com/commonjs/) module system, and should export a site configuration object, or a function that creates it.
+
+Examples:
 
 ```js title="docusaurus.config.js"
 module.exports = {
-  // site config...
+  title: 'Docusaurus',
+  url: 'https://docusaurus.io',
+  // your site config ...
 };
 ```
 
-<details>
-<summary>Config files also support config creator functions and async code.</summary>
-
 ```js title="docusaurus.config.js"
-module.exports = function configCreator() {
+module.exports = async function createConfigAsync() {
   return {
-    // site config...
+    title: 'Docusaurus',
+    url: 'https://docusaurus.io',
+    // your site config ...
   };
 };
 ```
 
-```js title="docusaurus.config.js"
-module.exports = async function configCreatorAsync() {
-  return {
-    // site config...
-  };
-};
-```
+:::tip
 
-```js title="docusaurus.config.js"
-module.exports = Promise.resolve({
-  // site config...
-});
-```
+Refer to [**Syntax to declare `docusaurus.config.js`**](docs/configuration.mdx#syntax-to-declare-docusaurus-config) for a more exhaustive list of examples and explanations.
 
-</details>
+:::
 
 ## Required fields {#required-fields}
 
diff --git a/website/docs/configuration.mdx b/website/docs/configuration.mdx
index 2d0055c943..d0689e1b54 100644
--- a/website/docs/configuration.mdx
+++ b/website/docs/configuration.mdx
@@ -16,6 +16,83 @@ Docusaurus has a unique take on configurations. We encourage you to congregate i
 
 Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors to be able to focus on documentation while still being able to customize the site.
 
+## Syntax to declare `docusaurus.config.js` {#syntax-to-declare-docusaurus-config}
+
+The `docusaurus.config.js` file is run in Node.js and should export either:
+
+- a **config object**
+- a **function** that creates the config object
+
+:::info
+
+The `docusaurus.config.js` file only supports the [**CommonJS**](https://flaviocopes.com/commonjs/) module system:
+
+- **Required:** use `module.exports = /* your config*/` to export your Docusaurus config
+- **Optional:** use `require("lib")` to import Node.js packages
+- **Optional:** use `await import("lib")` (dynamic import) in an async function to import ESM-Only Node.js packages
+
+:::
+
+Node.js gives us the ability to declare our Docusaurus configuration in various **equivalent ways**, and all the following config examples lead to the exact same result:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  title: 'Docusaurus',
+  url: 'https://docusaurus.io',
+  // your site config ...
+};
+```
+
+```js title="docusaurus.config.js"
+const config = {
+  title: 'Docusaurus',
+  url: 'https://docusaurus.io',
+  // your site config ...
+};
+
+module.exports = config;
+```
+
+```js title="docusaurus.config.js"
+module.exports = function configCreator() {
+  return {
+    title: 'Docusaurus',
+    url: 'https://docusaurus.io',
+    // your site config ...
+  };
+};
+```
+
+```js title="docusaurus.config.js"
+module.exports = async function createConfigAsync() {
+  return {
+    title: 'Docusaurus',
+    url: 'https://docusaurus.io',
+    // your site config ...
+  };
+};
+```
+
+:::tip Using ESM-only packages
+
+Using an async config creator can be useful to import ESM-only modules (notably most Remark plugins). It is possible to import such modules thanks to dynamic imports:
+
+```js title="docusaurus.config.js"
+module.exports = async function createConfigAsync() {
+  // Use a dynamic import instead of require('esm-lib')
+  // highlight-next-line
+  const lib = await import('lib');
+
+  return {
+    title: 'Docusaurus',
+    url: 'https://docusaurus.io',
+    // rest of your site config...
+  };
+};
+```
+
+:::
+
 ## What goes into a `docusaurus.config.js`? {#what-goes-into-a-docusaurusconfigjs}
 
 You should not have to write your `docusaurus.config.js` from scratch even if you are developing your site. All templates come with a `docusaurus.config.js` that includes defaults for the common options.