feat: add version picker for documentation

docs/Build.jl

@@ -78,7 +78,7 @@ function make(Hecke::Module; strict = false,
           repo = "github.com/thofma/Hecke.jl",
           devurl = "dev",
           devbranch = "master",
-          #deploy_url = "https://thofma.com/Hecke.jl",
+          deploy_url = "https://docs.hecke.thofma.com",
           #build_vitepress = !local_build,
          ),
       warnonly = warnonly,

docs/package.json

@@ -1,8 +1,8 @@
 {
   "devDependencies": {
-    "markdown-it": "^14.0.0",
+    "markdown-it": "^14.1.0",
     "markdown-it-mathjax3": "^4.3.2",
-    "vitepress": "^1.0.0-rc.43",
+    "vitepress": "^1.5.0",
     "vitepress-plugin-tabs": "^0.5.0",
     "vitest": "^1.3.0"
   },

docs/src/.vitepress/config.mts

@@ -3,6 +3,27 @@ import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
 import mathjax3 from "markdown-it-mathjax3";
 import footnote from "markdown-it-footnote";
 
+function getBaseRepository(base: string): string {
+  if (!base || base === '/') return '/';
+  const parts = base.split('/').filter(Boolean);
+  return parts.length > 0 ? `/${parts[0]}/` : '/';
+}
+
+const baseTemp = {
+  base: 'REPLACE_ME_DOCUMENTER_VITEPRESS',// TODO: replace this in makedocs!
+}
+
+const navTemp = {
+  nav: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+}
+
+const nav = [
+  ...navTemp.nav,
+  {
+    component: 'VersionPicker'
+  }
+]
+
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
   base: 'REPLACE_ME_DOCUMENTER_VITEPRESS',// TODO: replace this in makedocs!
@@ -11,7 +32,13 @@ export default defineConfig({
   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: `${getBaseRepository(baseTemp.base)}versions.js`}],
+    // ['script', {src: '/versions.js'], for custom domains, I guess if deploy_url is available.
+    ['script', {src: `${baseTemp.base}siteinfo.js`}]
+  ],
+
   ignoreDeadLinks: true,
   appearance: 'dark',
 
@@ -42,10 +69,7 @@ export default defineConfig({
       { text: 'Tutorials', link: '/tutorials/' },
       { text: 'How-to Guides', link: '/howto/' },
       {
-        text: 'Versions', items: [
-          { text: 'Stable', link: 'https://thofma.com/Hecke.jl/stable/' },
-          { text: 'Dev', link: 'https://thofma.com/Hecke.jl/dev/' }
-        ]
+        component: 'VersionPicker'
       }
     ],
     sidebar: {

docs/src/.vitepress/theme/VersionPicker.vue

@@ -0,0 +1,142 @@
+<!-- Adapted from https://github.com/MakieOrg/Makie.jl/blob/master/docs/src/.vitepress/theme/VersionPicker.vue -->
+
+<script setup lang="ts">
+import { ref, onMounted, computed } from 'vue'
+import { useData } from 'vitepress'
+import VPNavBarMenuGroup from 'vitepress/dist/client/theme-default/components/VPNavBarMenuGroup.vue'
+import VPNavScreenMenuGroup from 'vitepress/dist/client/theme-default/components/VPNavScreenMenuGroup.vue'
+
+// Extend the global Window interface to include DOC_VERSIONS and DOCUMENTER_CURRENT_VERSION
+declare global {
+  interface Window {
+    DOC_VERSIONS?: string[];
+    DOCUMENTER_CURRENT_VERSION?: string;
+  }
+}
+
+const props = defineProps<{
+  screenMenu?: boolean
+}>()
+
+const versions = ref<Array<{ text: string, link: string }>>([]);
+const currentVersion = ref('Versions');
+const isClient = ref(false);
+const { site } = useData()
+
+const isLocalBuild = () => {
+  return typeof window !== 'undefined' && (window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1');
+}
+
+const getBaseRepository = () => {
+  if (typeof window === 'undefined') return ''; // Handle server-side rendering (SSR)
+  const { origin, pathname } = window.location;
+  // Check if it's a GitHub Pages (or similar) setup
+  if (origin.includes('github.io')) {
+    // Extract the first part of the path as the repository name
+    const pathParts = pathname.split('/').filter(Boolean);
+    const baseRepo = pathParts.length > 0 ? `/${pathParts[0]}` : '';
+    return `${origin}${baseRepo}`;
+  } else {
+    // For custom domains, use just the origin (e.g., https://docs.makie.org)
+    return origin;
+  }
+};
+
+const waitForScriptsToLoad = () => {
+  return new Promise<boolean>((resolve) => {
+    if (isLocalBuild()) {
+      resolve(false);
+      return;
+    }
+    const checkInterval = setInterval(() => {
+      if (window.DOC_VERSIONS && window.DOCUMENTER_CURRENT_VERSION) {
+        clearInterval(checkInterval);
+        resolve(true);
+      }
+    }, 100);
+    // Timeout after 5 seconds
+    setTimeout(() => {
+      clearInterval(checkInterval);
+      resolve(false);
+    }, 5000);
+  });
+};
+
+const loadVersions = async () => {
+  if (typeof window === 'undefined') return; // Guard for SSR
+
+  try {
+    if (isLocalBuild()) {
+      // Handle the local build scenario directly
+      const fallbackVersions = ['dev'];
+      versions.value = fallbackVersions.map(v => ({
+        text: v,
+        link: '/'
+      }));
+      currentVersion.value = 'dev';
+    } else {
+      // For non-local builds, wait for scripts to load
+      const scriptsLoaded = await waitForScriptsToLoad();
+      const getBaseRepositoryPath = computed(() => {
+        return getBaseRepository();
+      });
+
+      if (scriptsLoaded && window.DOC_VERSIONS && window.DOCUMENTER_CURRENT_VERSION) {
+        versions.value = window.DOC_VERSIONS.map((v: string) => ({
+          text: v,
+          link: `${getBaseRepositoryPath.value}/${v}/`
+        }));
+        currentVersion.value = window.DOCUMENTER_CURRENT_VERSION;
+      } else {
+        // Fallback logic if scripts fail to load or are not available
+        const fallbackVersions = ['dev'];
+        versions.value = fallbackVersions.map(v => ({
+          text: v,
+          link: `${getBaseRepositoryPath.value}/${v}/`
+        }));
+        currentVersion.value = 'dev';
+      }
+    }
+  } catch (error) {
+    console.warn('Error loading versions:', error);
+    // Use fallback logic in case of an error
+    const fallbackVersions = ['dev'];
+    const getBaseRepositoryPath = computed(() => {
+        return getBaseRepository();
+      });
+    versions.value = fallbackVersions.map(v => ({
+      text: v,
+      link: `${getBaseRepositoryPath.value}/${v}/`
+    }));
+    currentVersion.value = 'dev';
+  }
+  isClient.value = true;
+};
+
+onMounted(loadVersions);
+</script>
+
+<template>
+  <template v-if="isClient">
+    <VPNavBarMenuGroup
+      v-if="!screenMenu && versions.length > 0"
+      :item="{ text: currentVersion, items: versions }"
+      class="VPVersionPicker"
+    />
+    <VPNavScreenMenuGroup
+      v-else-if="screenMenu && versions.length > 0"
+      :text="currentVersion"
+      :items="versions"
+      class="VPVersionPicker"
+    />
+  </template>
+</template>
+
+<style scoped>
+.VPVersionPicker :deep(button .text) {
+  color: var(--vp-c-text-1) !important;
+}
+.VPVersionPicker:hover :deep(button .text) {
+  color: var(--vp-c-text-2) !important;
+}
+</style>

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

@@ -2,18 +2,14 @@
 import { h } from 'vue'
 import type { Theme } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
-
+import VersionPicker from "./VersionPicker.vue"
 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)
+    enhanceAppWithTabs(app);
+    app.component('VersionPicker', VersionPicker);
   }
-} satisfies Theme
+} satisfies Theme