feat: Sidebar enhancements

src/generators/web/README.md

@@ -53,17 +53,17 @@ import { project, repository, editURL } from '#theme/config';
 
 All scalar (non-object) configuration values are automatically exported. The defaults include:
 
-| Export                   | Type                           | Description                                                                                         |
-| ------------------------ | ------------------------------ | --------------------------------------------------------------------------------------------------- |
-| `project`                | `string`                       | Project name (e.g. `'Node.js'`)                                                                     |
-| `repository`             | `string`                       | GitHub repository in `owner/repo` format                                                            |
-| `version`                | `string`                       | Current version label (e.g. `'v22.x'`)                                                              |
-| `versions`               | `Array<{ url, label, major }>` | Pre-computed version entries with labels and URL templates (only `{path}` remains for per-page use) |
-| `editURL`                | `string`                       | Partially populated "edit this page" URL template (only `{path}` remains)                           |
-| `pages`                  | `Array<[string, string]>`      | Sorted `[name, path]` tuples for sidebar navigation                                                 |
-| `useAbsoluteURLs`        | `boolean`                      | Whether internal links use absolute URLs (mirrors config value)                                     |
-| `baseURL`                | `string`                       | Base URL for the documentation site (used when `useAbsoluteURLs` is `true`)                         |
-| `languageDisplayNameMap` | `Map<string, string>`          | Shiki language alias → display name map for code blocks                                             |
+| Export                   | Type                                            | Description                                                                                           |
+| ------------------------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `project`                | `string`                                        | Project name (e.g. `'Node.js'`)                                                                       |
+| `repository`             | `string`                                        | GitHub repository in `owner/repo` format                                                              |
+| `version`                | `string`                                        | Current version label (e.g. `'v22.x'`)                                                                |
+| `versions`               | `Array<{ url, label, major }>`                  | Pre-computed version entries with labels and URL templates (only `{path}` remains for per-page use)   |
+| `editURL`                | `string`                                        | Partially populated "edit this page" URL template (only `{path}` remains)                             |
+| `pages`                  | `Array<[number, { heading, path, category? }]>` | Sorted `[weight, page]` tuples for sidebar navigation (explicit weights first, then default ordering) |
+| `useAbsoluteURLs`        | `boolean`                                       | Whether internal links use absolute URLs (mirrors config value)                                       |
+| `baseURL`                | `string`                                        | Base URL for the documentation site (used when `useAbsoluteURLs` is `true`)                           |
+| `languageDisplayNameMap` | `Map<string, string>`                           | Shiki language alias → display name map for code blocks                                               |
 
 #### Usage in custom components
 
@@ -77,16 +77,19 @@ export default ({ metadata }) => (
   <nav>
     <p>Current: {version}</p>
     <ul>
-      {pages.map(([name, path]) => (
-        <li key={path}>
-          <a href={`${path}.html`}>{name}</a>
+      {pages.map(([weight, page]) => (
+        <li key={page.path} data-weight={weight}>
+          <a href={`${page.path}.html`}>{page.heading}</a>
         </li>
       ))}
     </ul>
   </nav>
 );
 ```
 
+If a page defines `weight` in frontmatter, lower values are listed first.
+Pages without `weight` use `-1` and keep the default upstream ordering.
+
 ### Layout props
 
 The `Layout` component receives the following props:

src/generators/web/ui/components/SideBar/index.jsx

@@ -2,66 +2,39 @@ import Select from '@node-core/ui-components/Common/Select';
 import SideBar from '@node-core/ui-components/Containers/Sidebar';
 
 import styles from './index.module.css';
-import { relativeOrAbsolute } from '../../utils/relativeOrAbsolute.mjs';
+import {
+  buildSideBarGroups,
+  getCompatibleVersions,
+  redirect,
+} from './utils/index.mjs';
 
 import { project, version, versions, pages } from '#theme/config';
 
-/**
- * Extracts the major version number from a version string.
- * @param {string} v - Version string (e.g., 'v14.0.0', '14.0.0')
- * @returns {number}
- */
-const getMajorVersion = v => parseInt(String(v).match(/\d+/)?.[0] ?? '0', 10);
-
-/**
- * Redirect to a URL
- * @param {string} url URL
- */
-const redirect = url => (window.location.href = url);
-
 /**
  * Sidebar component for MDX documentation with version selection and page navigation
  * @param {{ metadata: import('../../types').SerializedMetadata }} props
  */
 export default ({ metadata }) => {
-  const introducedMajor = getMajorVersion(
-    metadata.added ?? metadata.introduced_in
-  );
-
+  // Build sidebar groups from metadata, categorizing pages and preserving order
+  const groups = buildSideBarGroups(pages, metadata);
   // Filter pre-computed versions by compatibility and resolve per-page URL
-  const compatibleVersions = versions
-    .filter(v => v.major >= introducedMajor)
-    .map(({ url, label }) => ({
-      value: url.replace('{path}', metadata.path),
-      label,
-    }));
-
-  const items = pages.map(([heading, path]) => ({
-    label: heading,
-    link:
-      metadata.path === path
-        ? `${metadata.basename}.html`
-        : `${relativeOrAbsolute(path, metadata.path)}.html`,
-  }));
+  const compatibleVersions = getCompatibleVersions(versions, metadata);
 
   return (
     <SideBar
       pathname={`${metadata.basename}.html`}
-      groups={[{ groupName: 'API Documentation', items }]}
+      groups={groups}
       onSelect={redirect}
       as={props => <a {...props} rel="prefetch" />}
       title="Navigation"
     >
-      <div>
-        <Select
-          label={`${project} version`}
-          values={compatibleVersions}
-          inline={true}
-          className={styles.select}
-          placeholder={version}
-          onChange={redirect}
-        />
-      </div>
+      <Select
+        label={`${project} version`}
+        values={compatibleVersions}
+        className={styles.select}
+        placeholder={version}
+        onChange={redirect}
+      />
     </SideBar>
   );
 };

src/generators/web/ui/components/SideBar/index.module.css

@@ -2,3 +2,8 @@
   width: 100%;
   margin-bottom: -1rem;
 }
+
+/* Override the min-width of the select component used for version selection in the sidebar */
+.select button[role='combobox'] {
+  min-width: initial;
+}