fix(metadata): strip directory prefix when converting nested .md link to .html

src/generators/metadata/utils/__tests__/parse.test.mjs

@@ -220,6 +220,57 @@ describe('parseApiDoc', () => {
 
       assert.strictEqual(findLink(entry)?.url, 'events.html#some-section');
     });
+
+    it('strips subdirectory prefix from nested .md links', () => {
+      const tree = u('root', [
+        h('fs'),
+        u('paragraph', [
+          u('link', { url: 'namespaces/comparators.md' }, [
+            u('text', 'comparators'),
+          ]),
+        ]),
+      ]);
+      const [entry] = parseApiDoc({ path, tree }, typeMap);
+
+      assert.strictEqual(findLink(entry)?.url, 'comparators.html');
+    });
+
+    it('strips subdirectory prefix and preserves hash fragments', () => {
+      const tree = u('root', [
+        h('fs'),
+        u('paragraph', [
+          u('link', { url: 'namespaces/comparators.md#some-section' }, [
+            u('text', 'comparators'),
+          ]),
+        ]),
+      ]);
+      const [entry] = parseApiDoc({ path, tree }, typeMap);
+
+      assert.strictEqual(findLink(entry)?.url, 'comparators.html#some-section');
+    });
+
+    it('ignores .md full URLs with any protocol', () => {
+      const protocolLinks = [
+        'https://github.com/example/config.md',
+        'http://internal-server.com/docs.md',
+        'file:///C:/Shared/docs/readme.md',
+      ];
+
+      for (const url of protocolLinks) {
+        const tree = u('root', [
+          h('fs'),
+          u('paragraph', [u('link', { url }, [u('text', 'external link')])]),
+        ]);
+        const [entry] = parseApiDoc({ path, tree }, typeMap);
+
+        // Assert that the URL comes out exactly as it went in
+        assert.strictEqual(
+          findLink(entry)?.url,
+          url,
+          `Failed to ignore protocol: ${url}`
+        );
+      }
+    });
   });
 
   describe('document without headings', () => {

src/generators/metadata/utils/visitors.mjs

@@ -1,4 +1,5 @@
 'use strict';
+import { basename } from 'node:path/posix';
 
 import { SKIP } from 'unist-util-visit';
 
@@ -16,9 +17,13 @@ import { transformNodesToString } from '../../../utils/unist.mjs';
  * @param {import('@types/mdast').Link} node A Markdown link node
  */
 export const visitMarkdownLink = node => {
+  // REJECT PROTOCOLS: Catches http:, https:, mailto:, ftp:, file:, vscode:, etc.
+  if (/^[a-z]+:/i.test(node.url)) {
+    return [SKIP];
+  }
   node.url = node.url.replace(
     QUERIES.markdownUrl,
-    (_, filename, hash = '') => `${filename}.html${hash}`
+    (_, filename, hash = '') => `${basename(filename)}.html${hash}`
   );
 
   return [SKIP];