From 5df63998bba3124fe5514f012b3d55b588a0b6fc Mon Sep 17 00:00:00 2001 From: Thad Guidry Date: Sat, 29 Apr 2023 13:18:33 +0800 Subject: [PATCH 1/9] link Configuration and API to each other at top --- website/docs/api/docusaurus.config.js.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/website/docs/api/docusaurus.config.js.mdx b/website/docs/api/docusaurus.config.js.mdx index 9b4ff8762820..9b48ecd33128 100644 --- a/website/docs/api/docusaurus.config.js.mdx +++ b/website/docs/api/docusaurus.config.js.mdx @@ -6,6 +6,12 @@ slug: /api/docusaurus-config # `docusaurus.config.js` +:::info + +Refer to the Getting Started [**Configuration**](docs/configuration.mdx) for examples. + +::: + ## Overview {#overview} `docusaurus.config.js` contains configurations for your site and is placed in the root directory of your site. From f11c40794adab01f7e3109fa28b9a296b3ac52a6 Mon Sep 17 00:00:00 2001 From: Thad Guidry Date: Sat, 29 Apr 2023 13:18:50 +0800 Subject: [PATCH 2/9] Link Configuration to API --- website/docs/configuration.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/website/docs/configuration.mdx b/website/docs/configuration.mdx index 734b6a21a8c6..30b301a737d8 100644 --- a/website/docs/configuration.mdx +++ b/website/docs/configuration.mdx @@ -6,6 +6,12 @@ description: Configuring your site's behavior through docusaurus.config.js and m import TOCInline from '@theme/TOCInline'; +:::info + +Check the [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.mdx) for an exhaustive list of options. + +::: + Docusaurus has a unique take on configurations. We encourage you to congregate information about your site into one place. We guard the fields of this file and facilitate making this data object accessible across your site. 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. @@ -20,7 +26,6 @@ The high-level overview of Docusaurus configuration can be categorized into: -For exact reference to each of the configurable fields, you may refer to [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.mdx). ### Site metadata {#site-metadata} From 4c2f857972b61f4eae9be07ac5e0f09a070318e1 Mon Sep 17 00:00:00 2001 From: Thad Guidry Date: Sat, 29 Apr 2023 14:16:15 +0800 Subject: [PATCH 3/9] Add info admonition about init config template --- website/docs/configuration.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/website/docs/configuration.mdx b/website/docs/configuration.mdx index 30b301a737d8..04fca860cc68 100644 --- a/website/docs/configuration.mdx +++ b/website/docs/configuration.mdx @@ -54,6 +54,14 @@ module.exports = { }; ``` +:::info[About the default `docusaurus.config.js` template] + +The init template `docusaurus.config.js` uses the `const config = { ... }` and it is equivalent to `module.exports = { ... }` shown throughout the examples. +There are various equivalent ways to declare your Docusaurus config, such as using creator functions and async code. +See: [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.mdx) + +::: + :::tip Docusaurus supports [**module shorthands**](./using-plugins.mdx#module-shorthands), allowing you to simplify the above configuration as: From 00555d5faf4025600f3af91221d49beed384e46b Mon Sep 17 00:00:00 2001 From: Thad Guidry Date: Thu, 4 May 2023 10:08:43 +0800 Subject: [PATCH 4/9] make new section and start on paragraphs --- website/docs/configuration.mdx | 77 +++++++++++++++++++++++++++++++--- 1 file changed, 71 insertions(+), 6 deletions(-) diff --git a/website/docs/configuration.mdx b/website/docs/configuration.mdx index 04fca860cc68..146a73edc4e0 100644 --- a/website/docs/configuration.mdx +++ b/website/docs/configuration.mdx @@ -16,6 +16,77 @@ 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 + +The init template `docusaurus.config.js` uses the `const config = { ... }` and it is equivalent to `module.exports = { ... }` shown throughout the examples. +There are various equivalent ways to declare your Docusaurus config, such as using creator functions and async code. +See: [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.mdx) + +Here is a verbose example using most of the syntax that is available ([docusaurus.config.js API](api/docusaurus.config.js.mdx), JS, Node, constants, variables, etc.): + +```js title="docusaurus.config.js" +const path = require('path'); +const npm2yarn = require('@docusaurus/remark-plugin-npm2yarn'); +const versions = require('./versions.json'); +const VersionsArchived = require('./versionsArchived.json'); + +module.exports = async function createConfigAsync() { + return { + title: 'Docusaurus', + tagline: getLocalizedConfigValue('tagline'), + organizationName: 'facebook', + projectName: 'docusaurus', + baseUrl, + baseUrlIssueBanner: true, + url: 'https://docusaurus.io', + themes: ['live-codeblock', ...dogfoodingThemeInstances], + plugins: [ + [ + require.resolve('./src/plugins/changelog/index.js'), + { + blogTitle: 'Docusaurus changelog', + blogDescription: + 'Keep yourself up-to-date about new features in every release', + }, + ], + ['content-docs', + /** @type {import('@docusaurus/plugin-content-docs').Options} */ + ({ + id: 'community', + path: 'community', + routeBasePath: 'community', + editUrl: ({locale, versionDocsDirPath, docPath}) => { + if (locale !== defaultLocale) { + return `https://crowdin.com/project/docusaurus-v2/${locale}`; + } + return `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`; + }, + remarkPlugins: [npm2yarn], + editCurrentVersion: true, + sidebarPath: require.resolve('./sidebarsCommunity.js'), + showLastUpdateAuthor: true, + showLastUpdateTime: true, + }), + + ], + ], + }; +}; + +``` + +Or using a Promise: +```js title="docusaurus.config.js" +module.exports = Promise.resolve({ + // site config... +}); + +``` + +Since a config file is Javascript then import/require can be utilized to pull in libraries to help. (For advanced users, just know that we ) + +// TODO: link for nodejs import/require. And answer question about interoperability for CommonJS and ECMAScript modules. + ## 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. @@ -54,13 +125,7 @@ module.exports = { }; ``` -:::info[About the default `docusaurus.config.js` template] - -The init template `docusaurus.config.js` uses the `const config = { ... }` and it is equivalent to `module.exports = { ... }` shown throughout the examples. -There are various equivalent ways to declare your Docusaurus config, such as using creator functions and async code. -See: [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.mdx) -::: :::tip From e2b38a1fea3c2e1247a48dc09fdc2d8cb05f6351 Mon Sep 17 00:00:00 2001 From: Thad Guidry Date: Thu, 4 May 2023 10:18:34 +0800 Subject: [PATCH 5/9] remove info (previously merged) --- website/docs/api/docusaurus.config.js.mdx | 5 ----- 1 file changed, 5 deletions(-) diff --git a/website/docs/api/docusaurus.config.js.mdx b/website/docs/api/docusaurus.config.js.mdx index 9b48ecd33128..85275ede3b11 100644 --- a/website/docs/api/docusaurus.config.js.mdx +++ b/website/docs/api/docusaurus.config.js.mdx @@ -6,11 +6,6 @@ slug: /api/docusaurus-config # `docusaurus.config.js` -:::info - -Refer to the Getting Started [**Configuration**](docs/configuration.mdx) for examples. - -::: ## Overview {#overview} From c2e25337329cacf7ba713e185a3f2d53f65d3ec0 Mon Sep 17 00:00:00 2001 From: Thad Guidry Date: Thu, 4 May 2023 10:26:18 +0800 Subject: [PATCH 6/9] remove extra LF --- website/docs/api/docusaurus.config.js.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/website/docs/api/docusaurus.config.js.mdx b/website/docs/api/docusaurus.config.js.mdx index 85275ede3b11..9b4ff8762820 100644 --- a/website/docs/api/docusaurus.config.js.mdx +++ b/website/docs/api/docusaurus.config.js.mdx @@ -6,7 +6,6 @@ slug: /api/docusaurus-config # `docusaurus.config.js` - ## Overview {#overview} `docusaurus.config.js` contains configurations for your site and is placed in the root directory of your site. From 985573cd820c17fb212cfc35107cae868e941d76 Mon Sep 17 00:00:00 2001 From: Thad Guidry Date: Fri, 5 May 2023 08:58:23 +0800 Subject: [PATCH 7/9] fix some of the suggestions --- website/docs/configuration.mdx | 87 ++++++++++++---------------------- 1 file changed, 29 insertions(+), 58 deletions(-) diff --git a/website/docs/configuration.mdx b/website/docs/configuration.mdx index 146a73edc4e0..aefb50f1dbf4 100644 --- a/website/docs/configuration.mdx +++ b/website/docs/configuration.mdx @@ -6,87 +6,58 @@ description: Configuring your site's behavior through docusaurus.config.js and m import TOCInline from '@theme/TOCInline'; -:::info +Docusaurus has a unique take on configurations. We encourage you to congregate information about your site into one place. We guard the fields of this file and facilitate making this data object accessible across your site. -Check the [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.mdx) for an exhaustive list of options. +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. -::: +:::note -Docusaurus has a unique take on configurations. We encourage you to congregate information about your site into one place. We guard the fields of this file and facilitate making this data object accessible across your site. +The Docusaurus config file only supports the [CommonJS](https://flaviocopes.com/commonjs/) module system. -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. +Example: (`require("lib")` / `module.exports = /* your config*/`). + +::: -## Syntax to declare docusaurus.config.js +## Syntax to declare `docusaurus.config.js` {#syntax-to-declare-docusaurus-config} -The init template `docusaurus.config.js` uses the `const config = { ... }` and it is equivalent to `module.exports = { ... }` shown throughout the examples. -There are various equivalent ways to declare your Docusaurus config, such as using creator functions and async code. +The initial template `docusaurus.config.js` uses the `const config = { ... }` and it is equivalent to `module.exports = { ... }` shown throughout the examples. +There are many equivalent ways to declare your Docusaurus configuration. See: [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.mdx) -Here is a verbose example using most of the syntax that is available ([docusaurus.config.js API](api/docusaurus.config.js.mdx), JS, Node, constants, variables, etc.): +Configuration initial default: ```js title="docusaurus.config.js" -const path = require('path'); -const npm2yarn = require('@docusaurus/remark-plugin-npm2yarn'); -const versions = require('./versions.json'); -const VersionsArchived = require('./versionsArchived.json'); +const config = { + // site config... +} -module.exports = async function createConfigAsync() { +module.exports = config +``` + +Configuration files also support config creator functions and async code: + +```js title="docusaurus.config.js" +module.exports = function configCreator() { return { - title: 'Docusaurus', - tagline: getLocalizedConfigValue('tagline'), - organizationName: 'facebook', - projectName: 'docusaurus', - baseUrl, - baseUrlIssueBanner: true, - url: 'https://docusaurus.io', - themes: ['live-codeblock', ...dogfoodingThemeInstances], - plugins: [ - [ - require.resolve('./src/plugins/changelog/index.js'), - { - blogTitle: 'Docusaurus changelog', - blogDescription: - 'Keep yourself up-to-date about new features in every release', - }, - ], - ['content-docs', - /** @type {import('@docusaurus/plugin-content-docs').Options} */ - ({ - id: 'community', - path: 'community', - routeBasePath: 'community', - editUrl: ({locale, versionDocsDirPath, docPath}) => { - if (locale !== defaultLocale) { - return `https://crowdin.com/project/docusaurus-v2/${locale}`; - } - return `https://github.com/facebook/docusaurus/edit/main/website/${versionDocsDirPath}/${docPath}`; - }, - remarkPlugins: [npm2yarn], - editCurrentVersion: true, - sidebarPath: require.resolve('./sidebarsCommunity.js'), - showLastUpdateAuthor: true, - showLastUpdateTime: true, - }), - - ], - ], + // site config... }; }; +``` +```js title="docusaurus.config.js" +module.exports = async function createConfigAsync() { + return { + // site config... + }; +}; ``` -Or using a Promise: ```js title="docusaurus.config.js" module.exports = Promise.resolve({ // site config... }); - ``` -Since a config file is Javascript then import/require can be utilized to pull in libraries to help. (For advanced users, just know that we ) - -// TODO: link for nodejs import/require. And answer question about interoperability for CommonJS and ECMAScript modules. - ## 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. From 71f463c5f3f2be64dae104a4630b666a0bd8fc9d Mon Sep 17 00:00:00 2001 From: Thad Guidry Date: Fri, 5 May 2023 10:02:29 +0800 Subject: [PATCH 8/9] try to fix format issue --- website/docs/configuration.mdx | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/website/docs/configuration.mdx b/website/docs/configuration.mdx index 505137177f05..f602878b0500 100644 --- a/website/docs/configuration.mdx +++ b/website/docs/configuration.mdx @@ -26,18 +26,16 @@ Example: (`require("lib")` / `module.exports = /* your config*/`). ## Syntax to declare `docusaurus.config.js` {#syntax-to-declare-docusaurus-config} -The initial template `docusaurus.config.js` uses the `const config = { ... }` and it is equivalent to `module.exports = { ... }` shown throughout the examples. -There are many equivalent ways to declare your Docusaurus configuration. -See: [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.mdx) +The initial template `docusaurus.config.js` uses the `const config = { ... }` and it is equivalent to `module.exports = { ... }` shown throughout the examples. There are many equivalent ways to declare your Docusaurus configuration. See: [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.mdx) Configuration initial default: ```js title="docusaurus.config.js" const config = { // site config... -} +}; -module.exports = config +module.exports = config; ``` Configuration files also support config creator functions and async code: @@ -101,8 +99,6 @@ module.exports = { }; ``` - - :::tip Docusaurus supports [**module shorthands**](./using-plugins.mdx#module-shorthands), allowing you to simplify the above configuration as: From 2cd9b4efb91aca6259a77c8b0f8714c815bdecea Mon Sep 17 00:00:00 2001 From: sebastienlorber Date: Fri, 5 May 2023 11:36:20 +0200 Subject: [PATCH 9/9] better config docs --- website/docs/api/docusaurus.config.js.mdx | 33 +++++------- website/docs/configuration.mdx | 61 +++++++++++++++++------ 2 files changed, 59 insertions(+), 35 deletions(-) diff --git a/website/docs/api/docusaurus.config.js.mdx b/website/docs/api/docusaurus.config.js.mdx index 9b48ecd33128..d86a697b1a08 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 ... }; ``` -
-Config files also support config creator functions and async code. - ```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. -
+::: ## Required fields {#required-fields} diff --git a/website/docs/configuration.mdx b/website/docs/configuration.mdx index f602878b0500..d0689e1b549c 100644 --- a/website/docs/configuration.mdx +++ b/website/docs/configuration.mdx @@ -16,34 +16,49 @@ 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. -:::note +## Syntax to declare `docusaurus.config.js` {#syntax-to-declare-docusaurus-config} -The Docusaurus config file only supports the [CommonJS](https://flaviocopes.com/commonjs/) module system. +The `docusaurus.config.js` file is run in Node.js and should export either: -Example: (`require("lib")` / `module.exports = /* your config*/`). +- a **config object** +- a **function** that creates the config object -::: +:::info -## Syntax to declare `docusaurus.config.js` {#syntax-to-declare-docusaurus-config} +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 -The initial template `docusaurus.config.js` uses the `const config = { ... }` and it is equivalent to `module.exports = { ... }` shown throughout the examples. There are many equivalent ways to declare your Docusaurus configuration. See: [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.mdx) +::: -Configuration initial default: +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 = { - // site config... + title: 'Docusaurus', + url: 'https://docusaurus.io', + // your site config ... }; module.exports = config; ``` -Configuration files also support config creator functions and async code: - ```js title="docusaurus.config.js" module.exports = function configCreator() { return { - // site config... + title: 'Docusaurus', + url: 'https://docusaurus.io', + // your site config ... }; }; ``` @@ -51,17 +66,33 @@ module.exports = function configCreator() { ```js title="docusaurus.config.js" module.exports = async function createConfigAsync() { return { - // site config... + 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 = Promise.resolve({ - // site config... -}); +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.