Skip to content

Commit

Permalink
feat: add version picker for documentation (#1699)
Browse files Browse the repository at this point in the history
thofma authored Dec 8, 2024

Verified

This commit was signed with the committer’s verified signature.
ddevsr Denny Septian Panggabean
1 parent e76d83a commit 61a6a0c
Showing 5 changed files with 178 additions and 16 deletions.
2 changes: 1 addition & 1 deletion docs/Build.jl
Original file line number Diff line number Diff line change
@@ -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,
4 changes: 2 additions & 2 deletions docs/package.json
Original file line number Diff line number Diff line change
@@ -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"
},
34 changes: 29 additions & 5 deletions docs/src/.vitepress/config.mts
Original file line number Diff line number Diff line change
@@ -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: {
142 changes: 142 additions & 0 deletions docs/src/.vitepress/theme/VersionPicker.vue
Original file line number Diff line number Diff line change
@@ -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>
12 changes: 4 additions & 8 deletions docs/src/.vitepress/theme/index.ts
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 61a6a0c

Please sign in to comment.