feat(docs): cleanse .md from hyperlinks in compiled mkdocs

.github/workflows/deploy-docs.yml

@@ -103,6 +103,11 @@ jobs:
             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

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());