Rewrite url of stable docs via javascript (#3918)

* try out url rewriter script referencing documenter version variables

* clean up logic for actual use

* test also initial rewrite

* change to real version

docs/src/.vitepress/config.mts

@@ -3,15 +3,23 @@ import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
 import mathjax3 from "markdown-it-mathjax3";
 import footnote from "markdown-it-footnote";
 
+const baseTemp = {
+  base: 'REPLACE_ME_DOCUMENTER_VITEPRESS',// TODO: replace this in makedocs!
+}
+
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
-  base: 'REPLACE_ME_DOCUMENTER_VITEPRESS',// TODO: replace this in makedocs!
+  base: baseTemp.base,
   title: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
   description: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
   lastUpdated: true,
   cleanUrls: true,
   outDir: 'REPLACE_ME_DOCUMENTER_VITEPRESS', // This is required for MarkdownVitepress to work correctly...
-  head: [['link', { rel: 'icon', href: 'REPLACE_ME_DOCUMENTER_VITEPRESS_FAVICON' }]],
+  head: [
+    ['link', { rel: 'icon', href: 'REPLACE_ME_DOCUMENTER_VITEPRESS_FAVICON' }],
+    ['script', {src: '/versions.js'}],
+    ['script', {src: `${baseTemp.base}siteinfo.js`}]
+  ],
   ignoreDeadLinks: true,
 
   markdown: {

docs/src/.vitepress/theme/index.ts

@@ -1,19 +1,60 @@
 // .vitepress/theme/index.ts
-import { h } from 'vue'
-import type { Theme } from 'vitepress'
-import DefaultTheme from 'vitepress/theme'
+import { h, watch } from "vue";
+import type { Theme } from "vitepress";
+import DefaultTheme from "vitepress/theme";
 
-import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
-import './style.css'
+import { enhanceAppWithTabs } from "vitepress-plugin-tabs/client";
+import "./style.css";
 
 export default {
   extends: DefaultTheme,
   Layout() {
     return h(DefaultTheme.Layout, null, {
       // https://vitepress.dev/guide/extending-default-theme#layout-slots
-    })
+    });
   },
-  enhanceApp({ app, router, siteData }) {
-    enhanceAppWithTabs(app)
-  }
-} satisfies Theme
+  async enhanceApp({ app, router, siteData }) {
+    enhanceAppWithTabs(app);
+    // Only run this on the client. Not during build.
+    // this function replaces the version in the URL with the stable prefix whenever a
+    // new route is navigated to. VitePress does not support relative links all over the site,
+    // so urls will go to v0.XY even if we start at stable. This solution is not ideal as
+    // there is a noticeable delay between navigating to a new page and editing the url, but it's
+    // currently better than nothing, as users are bound to copy versioned links to the docs otherwise
+    // which will lead users to outdated docs in the future.
+    if (typeof window !== "undefined") {
+      function rewriteURL() {
+        // DOCUMENTER_NEWEST is defined in versions.js, DOCUMENTER_CURRENT_VERSION and DOCUMENTER_STABLE
+        // in siteinfo.js.
+        if (
+          window.DOCUMENTER_NEWEST === undefined ||
+          window.DOCUMENTER_CURRENT_VERSION === undefined ||
+          window.DOCUMENTER_STABLE === undefined
+        ) {
+          return;
+        }
+
+        // Current version is newest version, so we can rewrite the url
+        if (window.DOCUMENTER_NEWEST === window.DOCUMENTER_CURRENT_VERSION) {
+          const rewritten_url = window.location.href.replace(
+            window.DOCUMENTER_CURRENT_VERSION,
+            window.DOCUMENTER_STABLE
+          );
+          window.history.replaceState(
+            { additionalInformation: "URL rewritten to stable" },
+            "Makie",
+            rewritten_url
+          );
+          return;
+        }
+      }
+
+      // rewrite on router changes through vitepress
+      watch(() => router.route.data.relativePath, rewriteURL, {
+        immediate: true,
+      });
+      // also rewrite at initial load
+      document.addEventListener("DOMContentLoaded", rewriteURL);
+    }
+  },
+} satisfies Theme;