From 35aa39bddb9c6c201f2d3d3f98dd15d88f15244d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= Date: Wed, 23 Oct 2024 20:01:07 +0200 Subject: [PATCH] docs: mention config/sidebars run in Node.js runtime (#10608) --- .../templates/classic-typescript/docusaurus.config.ts | 2 ++ .../templates/classic-typescript/sidebars.ts | 2 ++ .../templates/classic/docusaurus.config.js | 2 ++ .../create-docusaurus/templates/classic/sidebars.js | 10 ++++++---- website/docs/api/docusaurus.config.js.mdx | 2 +- website/docs/api/plugins/plugin-content-docs.mdx | 2 +- website/docs/guides/docs/sidebar/index.mdx | 10 ++++++++-- 7 files changed, 22 insertions(+), 8 deletions(-) diff --git a/packages/create-docusaurus/templates/classic-typescript/docusaurus.config.ts b/packages/create-docusaurus/templates/classic-typescript/docusaurus.config.ts index 43fd29ff1144..344c456720af 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 acc7685acd59..289713975cdf 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 12ccdd0db039..2b8cdb8e866e 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 332758032214..f77355c3ef92 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. - */ -// @ts-check - -/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ + @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 ead47f8343e5..08b97c2821b3 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 8f26354b8189..fa9ddbf53e6a 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 04297334ce63..ae1d4ac400df 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