diff --git a/packages/create-docusaurus/templates/classic-typescript/docusaurus.config.ts b/packages/create-docusaurus/templates/classic-typescript/docusaurus.config.ts
index 43fd29ff11..344c456720 100644
--- a/packages/create-docusaurus/templates/classic-typescript/docusaurus.config.ts
+++ b/packages/create-docusaurus/templates/classic-typescript/docusaurus.config.ts
@@ -2,6 +2,8 @@ import {themes as prismThemes} from 'prism-react-renderer';
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
const config: Config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
diff --git a/packages/create-docusaurus/templates/classic-typescript/sidebars.ts b/packages/create-docusaurus/templates/classic-typescript/sidebars.ts
index acc7685acd..289713975c 100644
--- a/packages/create-docusaurus/templates/classic-typescript/sidebars.ts
+++ b/packages/create-docusaurus/templates/classic-typescript/sidebars.ts
@@ -1,5 +1,7 @@
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
/**
* Creating a sidebar enables you to:
- create an ordered group of docs
diff --git a/packages/create-docusaurus/templates/classic/docusaurus.config.js b/packages/create-docusaurus/templates/classic/docusaurus.config.js
index 12ccdd0db0..2b8cdb8e86 100644
--- a/packages/create-docusaurus/templates/classic/docusaurus.config.js
+++ b/packages/create-docusaurus/templates/classic/docusaurus.config.js
@@ -6,6 +6,8 @@
import {themes as prismThemes} from 'prism-react-renderer';
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
/** @type {import('@docusaurus/types').Config} */
const config = {
title: 'My Site',
diff --git a/packages/create-docusaurus/templates/classic/sidebars.js b/packages/create-docusaurus/templates/classic/sidebars.js
index 3327580322..f77355c3ef 100644
--- a/packages/create-docusaurus/templates/classic/sidebars.js
+++ b/packages/create-docusaurus/templates/classic/sidebars.js
@@ -1,3 +1,7 @@
+// @ts-check
+
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
/**
* Creating a sidebar enables you to:
- create an ordered group of docs
@@ -7,11 +11,9 @@
The sidebars can be generated from the filesystem, or explicitly defined here.
Create as many sidebars as you want.
+
+ @type {import('@docusaurus/plugin-content-docs').SidebarsConfig}
*/
-
-// @ts-check
-
-/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
// By default, Docusaurus generates a sidebar from the docs folder structure
tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
diff --git a/website/docs/api/docusaurus.config.js.mdx b/website/docs/api/docusaurus.config.js.mdx
index ead47f8343..08b97c2821 100644
--- a/website/docs/api/docusaurus.config.js.mdx
+++ b/website/docs/api/docusaurus.config.js.mdx
@@ -24,7 +24,7 @@ With a [TypeScript](../typescript-support.mdx) Docusaurus codebase your config f
:::
-This file is run in Node.js and should export a site configuration object, or a function that creates it.
+This file is **run in Node.js** and should export a site configuration object, or a function that creates it.
The `docusaurus.config.js` file supports:
diff --git a/website/docs/api/plugins/plugin-content-docs.mdx b/website/docs/api/plugins/plugin-content-docs.mdx
index 8f26354b81..fa9ddbf53e 100644
--- a/website/docs/api/plugins/plugin-content-docs.mdx
+++ b/website/docs/api/plugins/plugin-content-docs.mdx
@@ -41,7 +41,7 @@ Accepted fields:
| `tagsBasePath` | `string` | `'tags'` | URL route for the tags list page of your site. It is prepended to the `routeBasePath`. |
| `include` | `string[]` | `['**/*.{md,mdx}']` | Array of glob patterns matching Markdown files to be built, relative to the content path. |
| `exclude` | `string[]` | _See example configuration_ | Array of glob patterns matching Markdown files to be excluded. Serves as refinement based on the `include` option. |
-| `sidebarPath` | false \| string | `undefined` | Path to sidebar configuration. Use `false` to disable sidebars, or `undefined` to create a fully autogenerated sidebar. |
+| `sidebarPath` | false \| string | `undefined` | Path to a sidebars configuration file, loaded in a Node.js context. Use `false` to disable sidebars, or `undefined` to create a fully autogenerated sidebar. |
| `sidebarCollapsible` | `boolean` | `true` | Whether sidebar categories are collapsible by default. See also [Collapsible categories](/docs/sidebar/items#collapsible-categories) |
| `sidebarCollapsed` | `boolean` | `true` | Whether sidebar categories are collapsed by default. See also [Expanded categories by default](/docs/sidebar/items#expanded-categories-by-default) |
| `sidebarItemsGenerator` | [SidebarGenerator](#SidebarGenerator) | _Omitted_ | Function used to replace the sidebar items of type `'autogenerated'` with real sidebar items (docs, categories, links...). See also [Customize the sidebar items generator](/docs/sidebar/autogenerated#customize-the-sidebar-items-generator) |
diff --git a/website/docs/guides/docs/sidebar/index.mdx b/website/docs/guides/docs/sidebar/index.mdx
index 04297334ce..ae1d4ac400 100644
--- a/website/docs/guides/docs/sidebar/index.mdx
+++ b/website/docs/guides/docs/sidebar/index.mdx
@@ -12,8 +12,8 @@ Creating a sidebar is useful to:
To use sidebars on your Docusaurus site:
-1. Define a file that exports a dictionary of [sidebar objects](#sidebar-object).
-2. Pass this object into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.
+1. Define a sidebars file that exports a dictionary of [sidebar objects](#sidebar-object).
+2. Pass its path to the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.
```js title="docusaurus.config.js"
export default {
@@ -31,6 +31,12 @@ export default {
};
```
+:::important Node.js runtime
+
+The sidebars file is run with Node.js. You can't use or import browsers APIs, React or JSX in it.
+
+:::
+
This section serves as an overview of miscellaneous features of the doc sidebar. In the following sections, we will more systematically introduce the following concepts:
```mdx-code-block