From c252dd7b47115e38f5b9b111891fa6cc7a740f51 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Tue, 7 Oct 2025 19:28:59 +0200
Subject: [PATCH] site: automatically transform mkDocs links

---
 site/vitePlugins/markdown.ts | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/site/vitePlugins/markdown.ts b/site/vitePlugins/markdown.ts
index 5bed32af1..bc2573a8f 100644
--- a/site/vitePlugins/markdown.ts
+++ b/site/vitePlugins/markdown.ts
@@ -11,6 +11,7 @@ import remarkDirective from "remark-directive";
 import rehypeAutolinkHeadings from "rehype-autolink-headings";
 import { toc } from "mdast-util-toc";
 import type { Nodes } from "mdast";
+import path from "path";
 import {
   transformerNotationDiff,
   transformerNotationHighlight,
@@ -32,6 +33,7 @@ export default function (): PluginOption {
       matter(file, { strip: true });
       const html = await unified()
         .use(remarkParse)
+        .use(link_migration)
         .use(remarkGfm)
         .use(remarkDirective)
         .use(styleDirectives)
@@ -148,3 +150,29 @@ function styleDirectives() {
     });
   };
 }
+
+/**
+ * Rewrites relative links in mkDocs files to point to /docs/...
+ *
+ * For this to work the relative link must start at the docs root
+ */
+function link_migration() {
+  const pathPrefix = "/docs";
+  return (tree) => {
+    visit(tree, ["link", "definition"], (node) => {
+      // Skip external links
+      if (!node.url || node.url.match(/^(https?:)?\/\//)) return;
+
+      // Links pointing to /docs already
+      if (node.url.startsWith(pathPrefix + "/")) return;
+      // Skip anchors
+      if (node.url.startsWith("#")) return;
+
+      const cleanUrl = node.url
+        // Remove repeated leading ../  or ./
+        .replace(/^(\.\.\/|\.\/)+/, "")
+        .replace(/\.md$/, "");
+      node.url = path.posix.join(pathPrefix, cleanUrl);
+    });
+  };
+}