From 9107b8b1f681f2f3a9bfcf9aab3e6f0cfc8fcf4b Mon Sep 17 00:00:00 2001 From: avivkeller Date: Thu, 30 Jul 2026 18:22:11 -0700 Subject: [PATCH] feat: add configuration for nav --- .changeset/configurable-navigation.md | 6 ++ beta/doc-kit.config.mjs | 19 +++++ packages/core/src/generators/web/README.md | 54 ++++++++++++- packages/core/src/generators/web/index.mjs | 3 + packages/core/src/generators/web/types.d.ts | 11 +++ .../generators/web/ui/components/NavBar.jsx | 7 +- .../web/ui/components/SideBar/index.jsx | 67 +++++++++++----- .../core/src/generators/web/ui/types.d.ts | 1 + www/doc-kit.config.mjs | 36 +++++++-- www/theme/SideBar.jsx | 77 ------------------- 10 files changed, 174 insertions(+), 107 deletions(-) create mode 100644 .changeset/configurable-navigation.md delete mode 100644 www/theme/SideBar.jsx diff --git a/.changeset/configurable-navigation.md b/.changeset/configurable-navigation.md new file mode 100644 index 00000000..cecf529c --- /dev/null +++ b/.changeset/configurable-navigation.md @@ -0,0 +1,6 @@ +--- +'@node-core/doc-kit': patch +--- + +Add `web.navigation`, which supplies the sidebar groups (`navigation.sidebar`) +and the navigation bar items (`navigation.navbar`) from configuration. diff --git a/beta/doc-kit.config.mjs b/beta/doc-kit.config.mjs index ea3db2d8..07484c9c 100644 --- a/beta/doc-kit.config.mjs +++ b/beta/doc-kit.config.mjs @@ -2,5 +2,24 @@ export default { web: { remoteConfigUrl: 'https://raw.githubusercontent.com/nodejs/doc-kit/main/beta/site.json', + + navigation: { + // This preview is deployed at a subdomain, so + // these links need to be absolute + navbar: [ + { text: 'Learn', link: 'https://nodejs.org/en/learn' }, + { text: 'About', link: 'https://nodejs.org/en/about' }, + { text: 'Download', link: 'https://nodejs.org/en/download' }, + { text: 'Docs', link: 'https://nodejs.org/docs/latest/api/' }, + { + text: 'Contribute', + link: 'https://github.com/nodejs/node/blob/main/CONTRIBUTING.md', + }, + { + text: 'Courses', + link: 'https://training.linuxfoundation.org/openjs-certification-candidate-resources/', + }, + ], + }, }, }; diff --git a/packages/core/src/generators/web/README.md b/packages/core/src/generators/web/README.md index 22af6691..f49f59fb 100644 --- a/packages/core/src/generators/web/README.md +++ b/packages/core/src/generators/web/README.md @@ -25,6 +25,7 @@ The `web` generator accepts the following configuration options: | `imports` | `object` | See below | Object mapping `#theme/` aliases to component paths for customization | | `virtualImports` | `object` | `{}` | Additional virtual module mappings supplied to the server and client builds | | `components` | `object` | `{}` | Maps JSX tag names to component imports, enabling JSX-in-MDX (see below) | +| `navigation` | `object` | `{}` | Sidebar groups and navigation bar items (see below) | | `bundler` | `WebBundler` | Vite adapter | Adapter that renders server entries and writes the client and HTML output (see below) | ### `head` @@ -71,6 +72,56 @@ export default { > via `head`, including `og:title` (which mirrors the per-page title) and > `og:type`. The UI stylesheet bundles its fonts locally. +### `navigation` + +The `navigation` object supplies the site's two navigation surfaces. Both keys +are optional; omit either one to keep that component's default. + +| Key | Type | Description | +| --------- | ------- | ---------------------------------------------------------------------------------------------------------- | +| `sidebar` | `array` | Sidebar groups, each `{ groupName, items }`. Defaults to one `API Documentation` group holding every page. | +| `navbar` | `array` | Navigation bar items, each `{ text, link, target? }`. Defaults to none, which renders no items. | + +Sidebar items are `{ label, link }` and may nest through an `items` array of +their own. A `label` is plain text, except that backticked spans render as +`` (``'`fs` Generator'``), matching how page headings are rendered. A +`link` is a page path without its extension (`/fs`, `/generators/web`): it is +resolved against the page being rendered, so it obeys `useAbsoluteURLs` and +highlights while it is the current page. Links starting with `http://` or +`https://` are used as authored. + +Navigation bar links are always used as authored, since they typically point +outside the generated site. Give them a `target` of `'_blank'` to open in a new +tab and mark them with an external-link icon. + +```js +// doc-kit.config.mjs +export default { + web: { + navigation: { + sidebar: [ + { + groupName: 'Guides', + items: [{ label: 'Getting started', link: '/getting-started' }], + }, + { + groupName: 'Reference', + items: [{ label: '`fs`', link: '/fs' }], + }, + ], + navbar: [ + { text: 'Learn', link: 'https://nodejs.org/en/learn' }, + { text: 'Download', link: 'https://nodejs.org/en/download' }, + ], + }, + }, +}; +``` + +The sidebar also renders a version ` - + {/* A site built without a `changelog` has no versions to switch between. */} + {versions.length > 0 && ( +
+ `. This site publishes a - * single version and passes an empty `changelog`, so `versions` is empty and the - * control has nothing to offer; it is omitted. - * - * @param {{ metadata: import('../../packages/core/src/generators/web/ui/types').SerializedMetadata }} props - */ -export default ({ metadata }) => { - const toItem = ([heading, path]) => ({ - label: renderLabel(heading), - link: - metadata.path === path - ? `${metadata.basename}.html` - : `${relativeOrAbsolute(path, metadata.path)}.html`, - }); - - const guides = orderGuides(pages.filter(page => !isGenerator(page))); - const generators = pages.filter(isGenerator); - - return ( - } - title="Navigation" - /> - ); -};