feat: navigation list sort weight added

Author: canerakdas

src/generators/web/README.md

@@ -54,7 +54,7 @@ import { title, repository, editURL } from '#theme/config';
 | `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                                                 |
+| `pages`                  | `Array<[number, { heading, path, category? }]>` | Sorted `[weight, page]` tuples for sidebar navigation (explicit weights first, then default ordering) |
 | `languageDisplayNameMap` | `Map<string, string>`          | Shiki language alias → display name map for code blocks                                             |
 
 #### Usage in custom components
@@ -69,16 +69,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/utils/__tests__/index.test.mjs

@@ -1,5 +1,3 @@
-'use strict';
-
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 
@@ -11,10 +9,10 @@ const {
 } = await import('../index.mjs');
 
 const pages = [
-  ['File System API', 'fs', 'File System'],
-  ['HTTP API', 'http', 'Networking'],
-  ['Path API', 'path', 'File System'],
-  ['Index', 'index'],
+  [1, { heading: 'File System API', path: 'fs', category: 'File System' }],
+  [2, { heading: 'HTTP API', path: 'http', category: 'Networking' }],
+  [3, { heading: 'Path API', path: 'path', category: 'File System' }],
+  [-1, { heading: 'Index', path: 'index' }],
 ];
 
 const versions = [
@@ -46,9 +44,9 @@ describe('buildSideBarGroups', () => {
 
   it('puts entries without category into an Others group at the end by default', () => {
     const uncategorizedPages = [
-      ['Buffer', 'buffer', 'Binary'],
-      ['Unknown', 'unknown'],
-      ['Config', 'config', ''],
+      [1, { heading: 'Buffer', path: 'buffer', category: 'Binary' }],
+      [-1, { heading: 'Unknown', path: 'unknown' }],
+      [-1, { heading: 'Config', path: 'config', category: '' }],
     ];
     const metadata = { path: 'buffer', basename: 'buffer' };
 
@@ -64,7 +62,7 @@ describe('buildSideBarGroups', () => {
   it('uses a custom default group name when provided', () => {
     const metadata = { path: 'unknown', basename: 'unknown' };
     const result = buildSideBarGroups(
-      [['Unknown', 'unknown']],
+      [[-1, { heading: 'Unknown', path: 'unknown' }]],
       metadata,
       'General'
     );
@@ -113,9 +111,59 @@ describe('getSidebarItems', () => {
     const metadata = { path: 'guide/fs', basename: 'fs' };
     const result = getSidebarItems(
       [
-        ['File System API', 'guide/fs', 'File System'],
-        ['HTTP API', 'guide/http', 'Networking'],
-        ['Child API', 'guide/sub/child'],
+        [
+          1,
+          {
+            heading: 'File System API',
+            path: 'guide/fs',
+            category: 'File System',
+          },
+        ],
+        [
+          2,
+          { heading: 'HTTP API', path: 'guide/http', category: 'Networking' },
+        ],
+        [-1, { heading: 'Child API', path: 'guide/sub/child' }],
+      ],
+      metadata
+    );
+
+    assert.deepStrictEqual(result, [
+      {
+        label: 'File System API',
+        link: 'fs.html',
+        category: 'File System',
+      },
+      {
+        label: 'HTTP API',
+        link: 'http.html',
+        category: 'Networking',
+      },
+      {
+        label: 'Child API',
+        link: 'sub/child.html',
+        category: undefined,
+      },
+    ]);
+  });
+
+  it('maps the new [weight, page] tuple shape', () => {
+    const metadata = { path: 'guide/fs', basename: 'fs' };
+    const result = getSidebarItems(
+      [
+        [
+          10,
+          {
+            heading: 'File System API',
+            path: 'guide/fs',
+            category: 'File System',
+          },
+        ],
+        [
+          20,
+          { heading: 'HTTP API', path: 'guide/http', category: 'Networking' },
+        ],
+        [-1, { heading: 'Child API', path: 'guide/sub/child' }],
       ],
       metadata
     );

src/generators/web/ui/components/SideBar/utils/index.mjs

@@ -4,7 +4,7 @@ import { relative } from '../../../../../../utils/url.mjs';
  * Builds grouped sidebar navigation from categorized page entries.
  * Pages without a category are placed under the provided default group.
  *
- * @param {Array<[string, string, string?]>} pages - Array of page entries as [heading, path, category?]
+ * @param {Array<[number, { heading: string, path: string, category?: string }> >} pages
  * @param {{ path: string, basename: string }} metadata - Metadata for the current page, used to resolve links
  * @param {string} [defaultGroupName='Others'] - Name for the default group containing uncategorized pages
  * @returns {Array<{ groupName: string, items: Array<{ label: string, link: string }> }>}
@@ -53,19 +53,21 @@ export const buildSideBarGroups = (
 
 /**
  * Converts page entries to sidebar items with resolved links based on current page metadata.
- * @param {Array<[string, string, string?]>} pages
+ * @param {Array<[number, { heading: string, path: string, category?: string }> >} pages
  * @param {{ path: string, basename: string }} metadata
  * @returns {Array<{ label: string, link: string, category?: string }>}
  */
 export const getSidebarItems = (pages, metadata) =>
-  pages.map(([heading, path, category]) => ({
-    label: heading,
-    link:
-      metadata.path === path
-        ? `${metadata.basename}.html`
-        : `${relative(path, metadata.path)}.html`,
-    category,
-  }));
+  pages.map(([, { heading, path, category }]) => {
+    return {
+      label: heading,
+      link:
+        metadata.path === path
+          ? `${metadata.basename}.html`
+          : `${relative(path, metadata.path)}.html`,
+      category,
+    };
+  });
 
 /**
  * Extracts the major version number from a version string.

src/generators/web/ui/types.d.ts

@@ -15,7 +15,9 @@ declare module '#theme/config' {
     major: number;
   }>;
   export const editURL: string;
-  export const pages: Array<[string, string, string?]>;
+  export const pages: Array<
+    [number, { heading: string; path: string; category?: string }]
+  >;
   export const languageDisplayNameMap: Map<string, string>;
 }
 

src/generators/web/utils/__tests__/config.test.mjs

@@ -102,7 +102,7 @@ describe('buildVersionEntries', () => {
 });
 
 describe('buildPageList', () => {
-  it('returns sorted [name, path, category] tuples from input entries', () => {
+  it('returns sorted [weight, page] tuples from input entries', () => {
     const input = [
       makeEntry('http', 'HTTP', '/http'),
       makeEntry('fs', 'File System', '/fs'),
@@ -112,8 +112,11 @@ describe('buildPageList', () => {
 
     assert.equal(result.length, 2);
     // Sorted alphabetically by name
-    assert.deepStrictEqual(result[0], ['File System', '/fs', 'File System']);
-    assert.deepStrictEqual(result[1], ['HTTP', '/http', undefined]);
+    assert.deepStrictEqual(result[0], [
+      -1,
+      { heading: 'File System', path: '/fs', category: 'File System' },
+    ]);
+    assert.deepStrictEqual(result[1], [-1, { heading: 'HTTP', path: '/http' }]);
   });
 
   it('filters out entries whose heading depth is not 1', () => {
@@ -131,7 +134,41 @@ describe('buildPageList', () => {
     const result = buildPageList(input);
 
     assert.equal(result.length, 1);
-    assert.deepStrictEqual(result[0], ['File System', '/fs', 'File System']);
+    assert.deepStrictEqual(result[0], [
+      -1,
+      { heading: 'File System', path: '/fs', category: 'File System' },
+    ]);
+  });
+
+  it('prioritizes pages with explicit weight before default sorting', () => {
+    const input = [
+      {
+        data: {
+          api: 'http',
+          path: '/http',
+          heading: { depth: 1, data: { name: 'HTTP' } },
+          weight: 20,
+        },
+      },
+      {
+        data: {
+          api: 'fs',
+          path: '/fs',
+          category: 'File System',
+          heading: { depth: 1, data: { name: 'File System' } },
+          weight: '10',
+        },
+      },
+      makeEntry('buffer', 'Buffer', '/buffer'),
+    ];
+
+    const result = buildPageList(input);
+
+    assert.deepStrictEqual(result, [
+      [10, { heading: 'File System', path: '/fs', category: 'File System' }],
+      [20, { heading: 'HTTP', path: '/http' }],
+      [-1, { heading: 'Buffer', path: '/buffer' }],
+    ]);
   });
 });
 

src/generators/web/utils/__tests__/pages.test.mjs

@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import {
+  DEFAULT_PAGE_WEIGHT,
+  normalizePageWeight,
+  compareSidebarPageWeight,
+  buildSidebarPages,
+} from '../pages.mjs';
+
+describe('normalizePageWeight', () => {
+  it('returns finite numeric weights as-is', () => {
+    assert.equal(normalizePageWeight(10), 10);
+    assert.equal(normalizePageWeight(0), 0);
+    assert.equal(normalizePageWeight(-3), -3);
+  });
+
+  it('parses string numeric weights', () => {
+    assert.equal(normalizePageWeight('10'), 10);
+    assert.equal(normalizePageWeight('  5.5  '), 5.5);
+  });
+
+  it('falls back to default for invalid values', () => {
+    assert.equal(normalizePageWeight(undefined), DEFAULT_PAGE_WEIGHT);
+    assert.equal(normalizePageWeight(''), DEFAULT_PAGE_WEIGHT);
+    assert.equal(normalizePageWeight('abc'), DEFAULT_PAGE_WEIGHT);
+    assert.equal(normalizePageWeight(Number.NaN), DEFAULT_PAGE_WEIGHT);
+  });
+});
+
+describe('compareSidebarPageWeight', () => {
+  it('sorts explicit weights before default weight', () => {
+    assert.equal(compareSidebarPageWeight({ weight: 5 }, { weight: -1 }), -1);
+    assert.equal(compareSidebarPageWeight({ weight: -1 }, { weight: 5 }), 1);
+  });
+
+  it('sorts by ascending explicit weight', () => {
+    assert.equal(compareSidebarPageWeight({ weight: 1 }, { weight: 2 }), -1);
+    assert.equal(compareSidebarPageWeight({ weight: 3 }, { weight: 2 }), 1);
+  });
+
+  it('keeps relative weight when both sides are default', () => {
+    assert.equal(compareSidebarPageWeight({ weight: -1 }, { weight: -1 }), 0);
+  });
+});
+
+describe('buildSidebarPages', () => {
+  it('builds [weight, page] tuples and keeps optional category', () => {
+    const pages = buildSidebarPages([
+      {
+        path: '/buffer',
+        heading: { data: { name: 'Buffer' } },
+        weight: '20',
+      },
+      {
+        path: '/fs',
+        category: 'File System',
+        heading: { data: { name: 'File System' } },
+      },
+      {
+        path: '/http',
+        heading: { data: { name: 'HTTP' } },
+        weight: 10,
+      },
+    ]);
+
+    assert.deepStrictEqual(pages, [
+      [10, { heading: 'HTTP', path: '/http' }],
+      [20, { heading: 'Buffer', path: '/buffer' }],
+      [-1, { heading: 'File System', path: '/fs', category: 'File System' }],
+    ]);
+  });
+});

src/generators/web/utils/config.mjs

@@ -1,7 +1,6 @@
-'use strict';
-
 import { LANGS } from '@node-core/rehype-shiki';
 
+import { buildSidebarPages } from './pages.mjs';
 import getConfig from '../../../utils/configuration/index.mjs';
 import { populate } from '../../../utils/configuration/templates.mjs';
 import { getVersionFromSemVer } from '../../../utils/generators.mjs';
@@ -33,16 +32,12 @@ export function buildVersionEntries(config, pageURLBase) {
  * Pre-compute sorted page list for sidebar navigation.
  *
  * @param {Array<import('../../jsx-ast/utils/buildContent.mjs').JSXContent>} input
- * @returns {Array<[string, string, string?]>}
+ * @returns {Array<[number, { heading: string, path: string, category?: string }]>}
  */
 export function buildPageList(input) {
   const headNodes = getSortedHeadNodes(input.map(({ data }) => data));
 
-  return headNodes.map(({ path, category, heading }) => [
-    heading.data.name,
-    path,
-    category,
-  ]);
+  return buildSidebarPages(headNodes);
 }
 
 /**