refactor(utils): extract URL normalization to a shared utility

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;

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}

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,

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;

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 |

utils/helpers/urls.mjs

@@ -0,0 +1,15 @@
+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, '');
+  const combined = [prefix, path].filter(Boolean).join('/');
+  return `/${combined}`;
+};