versioning, picker component

docs/package.json

@@ -2,7 +2,7 @@
   "devDependencies": {
     "markdown-it": "^14.1.0",
     "markdown-it-mathjax3": "^4.3.2",
-    "vitepress": "^1.1.4",
+    "vitepress": "^1.3.4",
     "vitepress-plugin-tabs": "^0.5.0"
   },
   "scripts": {

docs/src/.vitepress/config.mts

@@ -4,6 +4,27 @@ import mathjax3 from "markdown-it-mathjax3";
 import footnote from "markdown-it-footnote";
 import { transformerMetaWordHighlight } from '@shikijs/transformers';
 
+function getBaseRepository(base: string): string {
+  if (!base) return '/';
+  // I guess if deploy_url is available. From where do I check this ?
+  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!
@@ -12,7 +33,12 @@ 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: '/DocumenterVitepress.jl/dev/favicon.ico' }]],
+  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`}]
+  ],
   vite: {
     build: {
       assetsInlineLimit: 0, // so we can tell whether we have created inlined images or not, we don't let vite inline them
@@ -43,7 +69,7 @@ export default defineConfig({
         detailedView: true
       }
     },
-    nav: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+    nav,
     sidebar: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
     editLink: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
     socialLinks: [

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

@@ -3,6 +3,7 @@ import { h } from 'vue'
 import type { Theme } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
 import AsideTrustees from '../../components/AsideTrustees.vue'
+import VersionPicker from "./VersionPicker.vue"
 
 import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
 import './style.css'
@@ -16,6 +17,7 @@ export default {
     })
   },
   enhanceApp({ app, router, siteData }) {
-    enhanceAppWithTabs(app)
+    enhanceAppWithTabs(app);
+    app.component('VersionPicker', VersionPicker);
   }
 } satisfies Theme

template/package.json

@@ -9,7 +9,7 @@
     "markdown-it": "^14.1.0",
     "markdown-it-footnote": "^4.0.0",
     "markdown-it-mathjax3": "^4.3.2",
-    "vitepress": "^1.1.4",
+    "vitepress": "^1.3.4",
     "vitepress-plugin-tabs": "^0.5.0"
   }
 }

template/src/.vitepress/config.mts

@@ -3,6 +3,28 @@ 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) return '/';
+  // I guess if deploy_url is available. From where do I check this ?
+  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 +33,12 @@ 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,
 
   markdown: {
@@ -34,7 +61,7 @@ export default defineConfig({
         detailedView: true
       }
     },
-    nav: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+    nav,
     sidebar: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
     editLink: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
     socialLinks: [