diff --git a/src/generators/web/README.md b/src/generators/web/README.md
index 4b4fe774..1030755a 100644
--- a/src/generators/web/README.md
+++ b/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,9 +77,9 @@ 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>
@@ -87,6 +87,9 @@ export default ({ metadata }) => (
 );
 ```
 
+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:
diff --git a/src/generators/web/ui/__mocks__/theme-config.mjs b/src/generators/web/ui/__mocks__/theme-config.mjs
new file mode 100644
index 00000000..d71e0780
--- /dev/null
+++ b/src/generators/web/ui/__mocks__/theme-config.mjs
@@ -0,0 +1,17 @@
+// Stub for the #theme/config virtual module used in tests.
+export const useAbsoluteURLs = false;
+export const baseURL = 'https://nodejs.org/';
+export const project = 'Node.js';
+export const repository = 'nodejs/node';
+export const title = 'Node.js';
+export const version = 'v22.0.0';
+export const versions = [];
+export const pages = [];
+export const editURL = '';
+export const languageDisplayNameMap = new Map();
+export const input = '';
+export const ignore = [];
+export const output = '';
+export const minify = false;
+export const ref = '';
+export const templatePath = '';
diff --git a/src/generators/web/ui/components/MetaBar/index.jsx b/src/generators/web/ui/components/MetaBar/index.jsx
index cc640f98..ba5f0645 100644
--- a/src/generators/web/ui/components/MetaBar/index.jsx
+++ b/src/generators/web/ui/components/MetaBar/index.jsx
@@ -3,10 +3,10 @@ import Badge from '@node-core/ui-components/Common/Badge';
 import MetaBar from '@node-core/ui-components/Containers/MetaBar';
 import GitHubIcon from '@node-core/ui-components/Icons/Social/GitHub';
 
-import styles from './index.module.css';
-
 import { editURL } from '#theme/config';
 
+import styles from './index.module.css';
+
 const iconMap = {
   JSON: CodeBracketIcon,
   MD: DocumentIcon,
diff --git a/src/generators/web/ui/components/NavBar.jsx b/src/generators/web/ui/components/NavBar.jsx
index 15fa85dd..78b98bbe 100644
--- a/src/generators/web/ui/components/NavBar.jsx
+++ b/src/generators/web/ui/components/NavBar.jsx
@@ -3,10 +3,11 @@ import NavBar from '@node-core/ui-components/Containers/NavBar';
 import styles from '@node-core/ui-components/Containers/NavBar/index.module.css';
 import GitHubIcon from '@node-core/ui-components/Icons/Social/GitHub';
 
+import { repository } from '#theme/config';
+
 import SearchBox from './SearchBox';
 import { useTheme } from '../hooks/useTheme.mjs';
 
-import { repository } from '#theme/config';
 import Logo from '#theme/Logo';
 
 /**
diff --git a/src/generators/web/ui/components/SideBar/index.jsx b/src/generators/web/ui/components/SideBar/index.jsx
index 40a987b7..1ba87dd1 100644
--- a/src/generators/web/ui/components/SideBar/index.jsx
+++ b/src/generators/web/ui/components/SideBar/index.jsx
@@ -1,67 +1,40 @@
 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 { 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);
+import styles from './index.module.css';
+import {
+  buildSideBarGroups,
+  getCompatibleVersions,
+  redirect,
+} from './utils/index.mjs';
 
 /**
  * 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>
   );
 };
diff --git a/src/generators/web/ui/components/SideBar/index.module.css b/src/generators/web/ui/components/SideBar/index.module.css
index 00b5c343..910f31a0 100644
--- a/src/generators/web/ui/components/SideBar/index.module.css
+++ b/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;
+}
diff --git a/src/generators/web/ui/components/SideBar/utils/__tests__/index.test.mjs b/src/generators/web/ui/components/SideBar/utils/__tests__/index.test.mjs
new file mode 100644
index 00000000..b886c9a8
--- /dev/null
+++ b/src/generators/web/ui/components/SideBar/utils/__tests__/index.test.mjs
@@ -0,0 +1,265 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+const {
+  buildSideBarGroups,
+  getSidebarItems,
+  getMajorVersion,
+  getCompatibleVersions,
+} = await import('../index.mjs');
+
+const pages = [
+  [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 = [
+  { major: 14, url: '/api/v14/{path}.html', label: 'v14' },
+  { major: 16, url: '/api/v16/{path}.html', label: 'v16' },
+  { major: 18, url: '/api/v18/{path}.html', label: 'v18' },
+];
+
+describe('buildSideBarGroups', () => {
+  it('groups entries by category and preserves insertion order', () => {
+    const metadata = { path: 'fs', basename: 'fs' };
+
+    const result = buildSideBarGroups(pages, metadata);
+
+    assert.deepStrictEqual(result, [
+      {
+        groupName: 'File System',
+        items: [
+          { label: 'File System API', link: 'fs.html' },
+          { label: 'Path API', link: 'path.html' },
+        ],
+      },
+      {
+        groupName: 'Networking',
+        items: [{ label: 'HTTP API', link: 'http.html' }],
+      },
+    ]);
+  });
+
+  it('puts entries without category into an Others group at the end by default', () => {
+    const uncategorizedPages = [
+      [1, { heading: 'Buffer', path: 'buffer', category: 'Binary' }],
+      [-1, { heading: 'Unknown', path: 'unknown' }],
+      [-1, { heading: 'Config', path: 'config', category: '' }],
+    ];
+    const metadata = { path: 'buffer', basename: 'buffer' };
+
+    const result = buildSideBarGroups(uncategorizedPages, metadata);
+
+    assert.equal(result.at(-1).groupName, 'Others');
+    assert.deepStrictEqual(result.at(-1).items, [
+      { label: 'Unknown', link: 'unknown.html' },
+      { label: 'Config', link: 'config.html' },
+    ]);
+  });
+
+  it('uses a custom default group name when provided', () => {
+    const metadata = { path: 'unknown', basename: 'unknown' };
+    const result = buildSideBarGroups(
+      [[-1, { heading: 'Unknown', path: 'unknown' }]],
+      metadata,
+      'General'
+    );
+
+    assert.deepStrictEqual(result, [
+      {
+        groupName: 'General',
+        items: [{ label: 'Unknown', link: 'unknown.html' }],
+      },
+    ]);
+  });
+
+  it('returns an empty array when given no entries', () => {
+    assert.deepStrictEqual(
+      buildSideBarGroups([], { path: 'fs', basename: 'fs' }),
+      []
+    );
+  });
+});
+
+describe('getSidebarItems', () => {
+  it('maps pages to sidebar items and keeps category values', () => {
+    const metadata = { path: 'fs', basename: 'fs' };
+    const result = getSidebarItems(pages.slice(0, 3), metadata);
+
+    assert.deepStrictEqual(result, [
+      {
+        label: 'File System API',
+        link: 'fs.html',
+        category: 'File System',
+      },
+      {
+        label: 'HTTP API',
+        link: 'http.html',
+        category: 'Networking',
+      },
+      {
+        label: 'Path API',
+        link: 'path.html',
+        category: 'File System',
+      },
+    ]);
+  });
+
+  it('uses basename html for the current page and relative links for others', () => {
+    const metadata = { path: 'guide/fs', basename: 'fs' };
+    const result = getSidebarItems(
+      [
+        [
+          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
+    );
+
+    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,
+      },
+    ]);
+  });
+});
+
+describe('getMajorVersion', () => {
+  it('extracts major version from "v" prefixed string', () => {
+    assert.strictEqual(getMajorVersion('v14.0.0'), 14);
+    assert.strictEqual(getMajorVersion('v18.12.0'), 18);
+  });
+
+  it('extracts major version without "v" prefix', () => {
+    assert.strictEqual(getMajorVersion('16.0.0'), 16);
+    assert.strictEqual(getMajorVersion('20.1.0'), 20);
+  });
+
+  it('handles single digit versions', () => {
+    assert.strictEqual(getMajorVersion('v4'), 4);
+    assert.strictEqual(getMajorVersion('9'), 9);
+  });
+
+  it('returns integer only', () => {
+    const result = getMajorVersion('v14.5.3');
+    assert.strictEqual(typeof result, 'number');
+    assert.strictEqual(result % 1, 0);
+  });
+});
+
+describe('getCompatibleVersions', () => {
+  it('includes versions with equal or greater major version', () => {
+    const metadata = { added: 'v14.0.0', path: 'fs.md' };
+    const result = getCompatibleVersions(versions, metadata);
+
+    assert.deepStrictEqual(result, [
+      { value: '/api/v14/fs.md.html', label: 'v14' },
+      { value: '/api/v16/fs.md.html', label: 'v16' },
+      { value: '/api/v18/fs.md.html', label: 'v18' },
+    ]);
+  });
+
+  it('filters out versions with lower major version', () => {
+    const metadata = { added: 'v18.0.0', path: 'fs.md' };
+    const result = getCompatibleVersions(versions, metadata);
+
+    assert.deepStrictEqual(result, [
+      { value: '/api/v18/fs.md.html', label: 'v18' },
+    ]);
+  });
+
+  it('uses introduced_in as fallback when added is missing', () => {
+    const metadata = { introduced_in: 'v16.0.0', path: 'fs.md' };
+    const result = getCompatibleVersions(versions, metadata);
+
+    assert.deepStrictEqual(result, [
+      { value: '/api/v16/fs.md.html', label: 'v16' },
+      { value: '/api/v18/fs.md.html', label: 'v18' },
+    ]);
+  });
+
+  it('defaults to v0 when no version info provided', () => {
+    const metadata = { path: 'fs.md' };
+    const result = getCompatibleVersions(versions, metadata);
+
+    assert.deepStrictEqual(result, [
+      { value: '/api/v14/fs.md.html', label: 'v14' },
+      { value: '/api/v16/fs.md.html', label: 'v16' },
+      { value: '/api/v18/fs.md.html', label: 'v18' },
+    ]);
+  });
+
+  it('replaces {path} placeholder in URL', () => {
+    const metadata = { added: 'v14.0.0', path: 'file/system' };
+    const result = getCompatibleVersions(versions, metadata);
+
+    result.forEach(item => {
+      assert.ok(!item.value.includes('{path}'));
+      assert.ok(item.value.includes(metadata.path));
+    });
+  });
+});
diff --git a/src/generators/web/ui/components/SideBar/utils/index.mjs b/src/generators/web/ui/components/SideBar/utils/index.mjs
new file mode 100644
index 00000000..e82f89c0
--- /dev/null
+++ b/src/generators/web/ui/components/SideBar/utils/index.mjs
@@ -0,0 +1,104 @@
+import { relativeOrAbsolute } from '../../../utils/relativeOrAbsolute.mjs';
+
+/**
+ * Builds grouped sidebar navigation from categorized page entries.
+ * Pages without a category are placed under the provided default group.
+ *
+ * @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 }> }>}
+ */
+export const buildSideBarGroups = (
+  pages,
+  metadata,
+  defaultGroupName = 'Others'
+) => {
+  const items = getSidebarItems(pages, metadata);
+  const groups = new Map();
+  const others = [];
+
+  // Group entries by category while preserving insertion order
+  for (const { label, link, category } of items) {
+    const linkFilename = link.split('/').at(-1);
+
+    // Skip index pages as they are typically the main entry point for a section
+    // and may not need to be listed separately in the sidebar.
+    if (linkFilename === 'index.html') {
+      continue;
+    }
+
+    if (!category) {
+      others.push({ label, link });
+      continue;
+    }
+
+    const groupItems = groups.get(category) ?? [];
+    groupItems.push({ label, link });
+    groups.set(category, groupItems);
+  }
+
+  // Convert the groups map to an array while preserving the original order of categories
+  const orderedGroups = [...groups.entries()].map(([groupName, items]) => ({
+    groupName,
+    items,
+  }));
+
+  if (others.length > 0) {
+    orderedGroups.push({ groupName: defaultGroupName, items: others });
+  }
+
+  return orderedGroups;
+};
+
+/**
+ * Converts page entries to sidebar items with resolved links based on current page metadata.
+ * @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 }]) => {
+    return {
+      label: heading,
+      link:
+        metadata.path === path
+          ? `${metadata.basename}.html`
+          : `${relativeOrAbsolute(path, metadata.path)}.html`,
+      category,
+    };
+  });
+
+/**
+ * Extracts the major version number from a version string.
+ * @param {string} v - Version string (e.g., 'v14.0.0', '14.0.0')
+ * @returns {number}
+ */
+export const getMajorVersion = v =>
+  parseInt(String(v).match(/\d+/)?.[0] ?? '0', 10);
+
+/**
+ * Filters pre-computed versions by compatibility and resolves per-page URL based on metadata.
+ * @param {Array<{ major: number, url: string, label: string }>} versions
+ * @param {{ added?: string, introduced_in?: string, path: string }} metadata
+ * @returns {Array<{ value: string, label: string }>}
+ */
+export const getCompatibleVersions = (versions, metadata) => {
+  const introducedMajor = getMajorVersion(
+    metadata.added ?? metadata.introduced_in
+  );
+
+  // Filter pre-computed versions by compatibility and resolve per-page URL
+  return versions
+    .filter(v => v.major >= introducedMajor)
+    .map(({ url, label }) => ({
+      value: url.replace('{path}', metadata.path),
+      label,
+    }));
+};
+
+/**
+ * Redirect to a URL
+ * @param {string} url URL
+ */
+export const redirect = url => (window.location.href = url);
diff --git a/src/generators/web/ui/package.json b/src/generators/web/ui/package.json
index a4382915..916581b8 100644
--- a/src/generators/web/ui/package.json
+++ b/src/generators/web/ui/package.json
@@ -1,3 +1,6 @@
 {
-  "sideEffects": false
+  "sideEffects": false,
+  "imports": {
+    "#theme/config": "./__mocks__/theme-config.mjs"
+  }
 }
diff --git a/src/generators/web/ui/types.d.ts b/src/generators/web/ui/types.d.ts
index 081061db..2728b903 100644
--- a/src/generators/web/ui/types.d.ts
+++ b/src/generators/web/ui/types.d.ts
@@ -30,8 +30,10 @@ declare module '#theme/config' {
     major: number;
   }>;
   export const editURL: string;
-  export const pages: Array<[string, string]>;
-  export const languageDisplayNameMap: Map<string[], string>;
+  export const pages: Array<
+    [number, { heading: string; path: string; category?: string }]
+  >;
+  export const languageDisplayNameMap: Map<string, string>;
 }
 
 // Omit Primitives from Metadata
diff --git a/src/generators/web/ui/utils/relativeOrAbsolute.mjs b/src/generators/web/ui/utils/relativeOrAbsolute.mjs
index e08b4876..f97a5fc8 100644
--- a/src/generators/web/ui/utils/relativeOrAbsolute.mjs
+++ b/src/generators/web/ui/utils/relativeOrAbsolute.mjs
@@ -1,7 +1,7 @@
-import { relative } from '../../../../utils/url.mjs';
-
 import { useAbsoluteURLs, baseURL } from '#theme/config';
 
+import { relative } from '../../../../utils/url.mjs';
+
 /**
  * Returns an absolute URL (based on baseURL) or a relative URL,
  * depending on the useAbsoluteURLs configuration option.
diff --git a/src/generators/web/utils/__tests__/config.test.mjs b/src/generators/web/utils/__tests__/config.test.mjs
index 4a64149b..20f81d60 100644
--- a/src/generators/web/utils/__tests__/config.test.mjs
+++ b/src/generators/web/utils/__tests__/config.test.mjs
@@ -43,6 +43,7 @@ const makeEntry = (api, name, path) => ({
   data: {
     api,
     path,
+    category: api === 'fs' ? 'File System' : undefined,
     heading: { depth: 1, data: { name } },
   },
 });
@@ -91,7 +92,7 @@ describe('buildVersionEntries', () => {
 });
 
 describe('buildPageList', () => {
-  it('returns sorted [name, path] tuples from input entries', () => {
+  it('returns sorted [weight, page] tuples from input entries', () => {
     const input = [
       makeEntry('http', 'HTTP', '/http'),
       makeEntry('fs', 'File System', '/fs'),
@@ -101,8 +102,11 @@ describe('buildPageList', () => {
 
     assert.equal(result.length, 2);
     // Sorted alphabetically by name
-    assert.deepStrictEqual(result[0], ['File System', '/fs']);
-    assert.deepStrictEqual(result[1], ['HTTP', '/http']);
+    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', () => {
@@ -120,7 +124,41 @@ describe('buildPageList', () => {
     const result = buildPageList(input);
 
     assert.equal(result.length, 1);
-    assert.deepStrictEqual(result[0], ['File System', '/fs']);
+    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' }],
+    ]);
   });
 });
 
diff --git a/src/generators/web/utils/__tests__/pages.test.mjs b/src/generators/web/utils/__tests__/pages.test.mjs
new file mode 100644
index 00000000..f8c3dbf8
--- /dev/null
+++ b/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' }],
+    ]);
+  });
+});
diff --git a/src/generators/web/utils/config.mjs b/src/generators/web/utils/config.mjs
index 00d7ae15..899cdb17 100644
--- a/src/generators/web/utils/config.mjs
+++ b/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';
@@ -34,11 +33,12 @@ export function buildVersionEntries(changelog, pageURLBase) {
  * Pre-compute sorted page list for sidebar navigation.
  *
  * @param {Array<import('../../jsx-ast/utils/buildContent.mjs').JSXContent>} input
- * @returns {Array<[string, string]>}
+ * @returns {Array<[number, { heading: string, path: string, category?: string }]>}
  */
 export function buildPageList(input) {
-  const headNodes = getSortedHeadNodes(input.map(e => e.data));
-  return headNodes.map(node => [node.heading.data.name, node.path]);
+  const headNodes = getSortedHeadNodes(input.map(({ data }) => data));
+
+  return buildSidebarPages(headNodes);
 }
 
 /**
diff --git a/src/generators/web/utils/pages.mjs b/src/generators/web/utils/pages.mjs
new file mode 100644
index 00000000..45bda65d
--- /dev/null
+++ b/src/generators/web/utils/pages.mjs
@@ -0,0 +1,81 @@
+/**
+ * Default weight used when a page does not define one.
+ */
+export const DEFAULT_PAGE_WEIGHT = -1;
+
+/**
+ * Normalizes a page weight value to a finite number, or falls back to default.
+ *
+ * @param {number|string} weight
+ * @returns {number}
+ */
+export const normalizePageWeight = weight => {
+  let candidate = NaN;
+
+  if (typeof weight === 'number') {
+    candidate = weight;
+  }
+
+  if (typeof weight === 'string') {
+    const trimmedWeight = weight.trim();
+
+    if (trimmedWeight !== '') {
+      candidate = Number(trimmedWeight);
+    }
+  }
+
+  return Number.isFinite(candidate) ? candidate : DEFAULT_PAGE_WEIGHT;
+};
+
+/**
+ * Sort callback for sidebar pages with explicit weight values.
+ *
+ * Pages with explicit weight are always shown first. Pages without explicit
+ * weight keep their existing upstream order.
+ *
+ * @param {{ weight: number }} a
+ * @param {{ weight: number }} b
+ * @returns {number}
+ */
+export const compareSidebarPageWeight = (a, b) => {
+  const aHasWeight = a.weight !== DEFAULT_PAGE_WEIGHT;
+  const bHasWeight = b.weight !== DEFAULT_PAGE_WEIGHT;
+
+  if (aHasWeight && bHasWeight) {
+    return a.weight - b.weight;
+  }
+
+  if (aHasWeight) {
+    return -1;
+  }
+
+  if (bHasWeight) {
+    return 1;
+  }
+
+  return 0;
+};
+
+/**
+ * Builds sidebar page tuples in [weight, page] format.
+ *
+ * @param {Array<import('../../metadata/types').MetadataEntry>} headNodes
+ * @returns {Array<[number, { heading: string, path: string, category?: string }]>}
+ */
+export const buildSidebarPages = headNodes =>
+  headNodes
+    .map(({ path, category, heading, weight }) => ({
+      heading: heading.data.name,
+      path,
+      category,
+      weight: normalizePageWeight(weight),
+    }))
+    .toSorted(compareSidebarPageWeight)
+    .map(({ heading, path, category, weight }) => [
+      weight,
+      {
+        heading,
+        path,
+        ...(category !== undefined ? { category } : {}),
+      },
+    ]);