From 1fdd42bc99901fb2f41646a893e3f934b3cd980a Mon Sep 17 00:00:00 2001
From: Mohamed Shams El-Deen <mohamedshamseldeen95@gmail.com>
Date: Sat, 11 Jul 2026 10:48:11 +0300
Subject: [PATCH 1/2] refactor(utils): extract URL normalization to a shared
 utility

---
 components/NavBar.jsx         |  2 +-
 components/SideBar.jsx        |  8 ++------
 plugins/processor/router.mjs  |  2 +-
 plugins/processor/site.mjs    |  2 +-
 plugins/processor/typeMap.mjs |  2 +-
 plugins/shared/urls.mjs       | 16 ----------------
 utils/helpers/urls.mjs        | 14 ++++++++++++++
 7 files changed, 20 insertions(+), 26 deletions(-)
 delete mode 100644 plugins/shared/urls.mjs
 create mode 100644 utils/helpers/urls.mjs

diff --git a/components/NavBar.jsx b/components/NavBar.jsx
index 19ba3062..68cfd085 100644
--- a/components/NavBar.jsx
+++ b/components/NavBar.jsx
@@ -7,7 +7,7 @@ import SearchBox from '@node-core/doc-kit/src/generators/web/ui/components/Searc
 import { useTheme } from '@node-core/doc-kit/src/generators/web/ui/hooks/useTheme.mjs';
 import { navbar } from '#theme/site';
 import { baseURL } from '#theme/config';
-import { toPublicLink } from '../plugins/shared/urls.mjs';
+import { toPublicLink } from '../utils/helpers/urls.mjs';
 import Logo from '#theme/Logo';
 
 const versionBase = new URL(baseURL).pathname;
diff --git a/components/SideBar.jsx b/components/SideBar.jsx
index ffa79547..dff33184 100644
--- a/components/SideBar.jsx
+++ b/components/SideBar.jsx
@@ -3,6 +3,7 @@ import SideBar from '@node-core/ui-components/Containers/Sidebar';
 import { major } from 'semver';
 import { sidebar } from '#theme/local/site';
 import { version } from '#theme/config';
+import { toPublicLink } from '../utils/helpers/urls.mjs';
 import versions from '../versions.json' with { type: 'json' };
 
 /** @param {string} url */
@@ -16,11 +17,6 @@ const isVersioned = Array.isArray(sidebar);
 // Versioned pages expose a version relative path, we prefix it so it matches the absolute sidebar links.
 const versionBase = isVersioned ? `/docs/api/v${version.major}.x` : '';
 
-const pathnameFor = path => {
-  const clean = path.replace(/\/index$/, '').replace(/^\//, '');
-  return (clean ? `${versionBase}/${clean}` : versionBase) || '/';
-};
-
 const groupsFor = path => {
   if (isVersioned) return sidebar;
 
@@ -39,7 +35,7 @@ const currentVersion = isVersioned ? versionBase : undefined;
 /** Docs sidebar, plus a webpack version picker on the versioned API docs. */
 export default ({ metadata }) => (
   <SideBar
-    pathname={pathnameFor(metadata.path)}
+    pathname={toPublicLink(metadata.path, versionBase)}
     groups={groupsFor(metadata.path)}
     onSelect={redirect}
     as={PrefetchLink}
diff --git a/plugins/processor/router.mjs b/plugins/processor/router.mjs
index 321ace1c..82536282 100644
--- a/plugins/processor/router.mjs
+++ b/plugins/processor/router.mjs
@@ -5,7 +5,7 @@ import { categoryForReflection } from '../shared/categories.mjs';
 import { getConstructorTitle, getMemberTitle } from '../shared/titles.mjs';
 import { getSourceMetadata, isTypePage } from './metadata.mjs';
 import { createTypePages, TYPE_PAGE_HEADING_KINDS } from './synthetic.mjs';
-import { normalizeLink } from '../shared/urls.mjs';
+import { normalizeLink } from '../../utils/helpers/urls.mjs';
 
 /**
  * The router owns the public Markdown shape. It keeps one class per file,
diff --git a/plugins/processor/site.mjs b/plugins/processor/site.mjs
index 29d644ae..a28d06fd 100644
--- a/plugins/processor/site.mjs
+++ b/plugins/processor/site.mjs
@@ -1,6 +1,6 @@
 import { ReflectionKind } from 'typedoc';
 import { CATEGORY_RULES } from '../shared/categories.mjs';
-import { toPublicLink } from '../shared/urls.mjs';
+import { toPublicLink } from '../../utils/helpers/urls.mjs';
 
 const SIDEBAR_KINDS =
   ReflectionKind.Project | ReflectionKind.Namespace | ReflectionKind.Class;
diff --git a/plugins/processor/typeMap.mjs b/plugins/processor/typeMap.mjs
index 5d28b3fe..12116c65 100644
--- a/plugins/processor/typeMap.mjs
+++ b/plugins/processor/typeMap.mjs
@@ -1,6 +1,6 @@
 import { ReflectionKind } from 'typedoc';
 import { isTypePage } from './metadata.mjs';
-import { normalizeLink } from '../shared/urls.mjs';
+import { normalizeLink } from '../../utils/helpers/urls.mjs';
 
 const TYPE_MAP_KINDS =
   ReflectionKind.Class |
diff --git a/plugins/shared/urls.mjs b/plugins/shared/urls.mjs
deleted file mode 100644
index 6397fa40..00000000
--- a/plugins/shared/urls.mjs
+++ /dev/null
@@ -1,16 +0,0 @@
-export const normalizeLink = url => {
-  if (!url) return '/';
-
-  return (
-    url
-      .replace(/\.(md|html)$/, '')
-      .replace(/\/index$/, '')
-      .replace(/^\//, '') || '/'
-  );
-};
-
-export const toPublicLink = (url, publicPath) => {
-  const path = normalizeLink(url);
-  const prefix = publicPath ? `${publicPath.replace(/\/$/g, '')}` : '';
-  return path ? `${prefix}/${path}` : prefix || '/';
-};
diff --git a/utils/helpers/urls.mjs b/utils/helpers/urls.mjs
new file mode 100644
index 00000000..35b6f442
--- /dev/null
+++ b/utils/helpers/urls.mjs
@@ -0,0 +1,14 @@
+export const normalizeLink = url => {
+  if (!url) return '';
+
+  return url
+    .replace(/\.(md|html)$/, '')
+    .replace(/\/index$/, '')
+    .replace(/^\//, '');
+};
+
+export const toPublicLink = (url, publicPath = '') => {
+  const path = normalizeLink(url);
+  const prefix = publicPath.replace(/\/$/g, '');
+  return path ? `${prefix}/${path}` : prefix || '/';
+};

From 35c7a4583be4faf69485b02d4e9bfeeb0b1cbd6b Mon Sep 17 00:00:00 2001
From: Mohamed Shams El-Deen <mohamedshamseldeen95@gmail.com>
Date: Sun, 12 Jul 2026 06:39:58 +0300
Subject: [PATCH 2/2] fix(urls): ensure the toPublicLink function return an
 absolute link

---
 utils/helpers/urls.mjs | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/utils/helpers/urls.mjs b/utils/helpers/urls.mjs
index 35b6f442..9df4c3b8 100644
--- a/utils/helpers/urls.mjs
+++ b/utils/helpers/urls.mjs
@@ -9,6 +9,7 @@ export const normalizeLink = url => {
 
 export const toPublicLink = (url, publicPath = '') => {
   const path = normalizeLink(url);
-  const prefix = publicPath.replace(/\/$/g, '');
-  return path ? `${prefix}/${path}` : prefix || '/';
+  const prefix = publicPath.replace(/^\/+|\/+$/g, '');
+  const combined = [prefix, path].filter(Boolean).join('/');
+  return `/${combined}`;
 };