From fd690592bac81599d3ca4eb21ce57612e2e87150 Mon Sep 17 00:00:00 2001
From: perf3ct <jonfuller2012@gmail.com>
Date: Sat, 13 Sep 2025 19:14:45 +0000
Subject: [PATCH] feat(docs): cleanse .md from hyperlinks in compiled mkdocs

---
 .github/workflows/deploy-docs.yml |  7 ++-
 scripts/fix-html-links.ts         | 71 +++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+), 1 deletion(-)
 create mode 100644 scripts/fix-html-links.ts

diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index 6558788c8..b80fadb69 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -102,7 +102,12 @@ jobs:
               exit $EXIT_CODE
             fi
           }
-      
+
+      - name: Fix HTML Links
+        run: |
+          # Remove .md extensions from links in generated HTML
+          pnpm tsx ./scripts/fix-html-links.ts site
+
       - name: Validate Built Site
         run: |
           # Basic validation that important files exist
diff --git a/scripts/fix-html-links.ts b/scripts/fix-html-links.ts
new file mode 100644
index 000000000..3eaddbdb7
--- /dev/null
+++ b/scripts/fix-html-links.ts
@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Post-process HTML files generated by MkDocs to remove .md extensions from links
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Process HTML content to remove .md extensions from links
+ */
+function fixHtmlLinks(content: string): string {
+    // Replace .md extensions in href attributes
+    // This regex matches href="...something.md" or href="...something.md#anchor"
+    return content.replace(/href="([^"]*?)\.md(#[^"]*)?"/g, 'href="$1$2"');
+}
+
+/**
+ * Recursively process all HTML files in a directory
+ */
+function processDirectory(dir: string): number {
+    let filesProcessed = 0;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+
+        if (entry.isDirectory()) {
+            // Recursively process subdirectories
+            filesProcessed += processDirectory(fullPath);
+        } else if (entry.isFile() && entry.name.endsWith('.html')) {
+            // Process HTML files
+            const content = fs.readFileSync(fullPath, 'utf-8');
+            const fixedContent = fixHtmlLinks(content);
+
+            if (content !== fixedContent) {
+                fs.writeFileSync(fullPath, fixedContent, 'utf-8');
+                console.log(`Fixed: ${path.relative(process.cwd(), fullPath)}`);
+                filesProcessed++;
+            }
+        }
+    }
+
+    return filesProcessed;
+}
+
+function main(): number {
+    const args = process.argv.slice(2);
+    const siteDir = args[0] || 'site';
+
+    const fullPath = path.resolve(siteDir);
+
+    if (!fs.existsSync(fullPath)) {
+        console.error(`Error: Directory '${fullPath}' does not exist`);
+        return 1;
+    }
+
+    console.log(`Processing HTML files in: ${fullPath}`);
+    console.log('-'.repeat(50));
+
+    const filesProcessed = processDirectory(fullPath);
+
+    console.log('-'.repeat(50));
+    console.log(`Processed ${filesProcessed} HTML files`);
+
+    return 0;
+}
+
+// Run the main function
+process.exit(main());
\ No newline at end of file