Skip to content

Commit

Permalink
feat: docs versioning (#1919)
Browse files Browse the repository at this point in the history
  • Loading branch information
jhaeu authored Dec 11, 2024
2 parents b95a1c8 + ca5f8fd commit 083adbc
Show file tree
Hide file tree
Showing 120 changed files with 9,226 additions and 209 deletions.
3 changes: 2 additions & 1 deletion .github/workflows/deploy-docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,8 @@ name: Deploy Backend Documentation to Pages
on:
# Runs on pushes targeting the `main` branch.
push:
branches: ["main"]
tags:
- latest

# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
Expand Down
185 changes: 185 additions & 0 deletions docs/.vitepress/components/VersionSwitcher.vue
Original file line number Diff line number Diff line change
@@ -0,0 +1,185 @@
<script setup lang="ts">
import { useRouter } from "vitepress"
import { computed, ref } from 'vue'
import VPMenuLink from 'vitepress/dist/client/theme-default/components/VPMenuLink.vue'
import VPFlyout from 'vitepress/dist/client/theme-default/components/VPFlyout.vue'
const props = defineProps<{
versioningPlugin: { versions: string[], latestVersion: string }
screenMenu?: boolean
}>();
const router = useRouter();
const sortedVersions = computed(() => {
let versions = props.versioningPlugin.versions.toReversed();
versions.push(props.versioningPlugin.latestVersion)
versions.sort((a: string, b: string) => {
// Extract the numeric parts after 'v' and compare them
const numA = parseInt(a.slice(1), 10);
const numB = parseInt(b.slice(1), 10);
// Sort in descending order
return numB - numA;
})
return versions
});
/**
* generates the correct link in the dropdown for the specific version
* @param version - the version text of the current dropdown entry
*/
function versionedLink(version: string): string {
let pathElementsToRemove = 2
if (!currentVersion.value.includes('latest')) {
pathElementsToRemove = 3
}
const sitePath = router.route.path.split('/').slice(pathElementsToRemove).join('/')
let returnPath = '/'
if (!version.includes('latest')) {
returnPath = `/${version}/`
}
return `${returnPath}${sitePath}`
}
const currentVersion = computed(() => {
let version = props.versioningPlugin.latestVersion;
for (const v of props.versioningPlugin.versions) {
if (router.route.path.split('/').includes(v)) {
version = v;
break;
}
}
return version;
});
const isOpen = ref(false);
const toggle = () => {
isOpen.value = !isOpen.value;
};
</script>

<template>
<VPFlyout v-if="!screenMenu" class="VPVersionSwitcher" icon="vpi-versioning" :button="currentVersion"
:label="'Switch Version'">
<div class="items">
<template v-for="version in sortedVersions" :key="version">
<VPMenuLink v-if="currentVersion != version" :item="{
text: version,
link: versionedLink(version)
}" />
</template>
</div>
</VPFlyout>
<div v-else class="VPScreenVersionSwitcher" :class="{ open: isOpen }">
<button class="button" aria-controls="navbar-group-version" :aria-expanded="isOpen" @click="toggle">
<span class="button-text"><span class="vpi-versioning icon" />Switch Version</span>
<span class="vpi-plus button-icon" />
</button>

<div id="navbar-group-version" class="items">
<template v-for="version in sortedVersions" :key="version">
<VPMenuLink :item="{
text: version,
link: versionedLink(version)
}" />
</template>
</div>
</div>
</template>

<style>
.vpi-versioning.option-icon {
margin-right: 2px !important;
}
.vpi-versioning {
--icon: url("data:image/svg+xml;charset=utf-8;base64,PHN2ZyB3aWR0aD0iNjRweCIgaGVpZ2h0PSI2NHB4IiB2aWV3Qm94PSIwIDAgMjQgMjQiIHN0cm9rZS13aWR0aD0iMi4yIiBmaWxsPSJub25lIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGNvbG9yPSIjMDAwMDAwIj48cGF0aCBkPSJNMTcgN0MxOC4xMDQ2IDcgMTkgNi4xMDQ1NyAxOSA1QzE5IDMuODk1NDMgMTguMTA0NiAzIDE3IDNDMTUuODk1NCAzIDE1IDMuODk1NDMgMTUgNUMxNSA2LjEwNDU3IDE1Ljg5NTQgNyAxNyA3WiIgc3Ryb2tlPSIjMDAwMDAwIiBzdHJva2Utd2lkdGg9IjIuMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIj48L3BhdGg+PHBhdGggZD0iTTcgN0M4LjEwNDU3IDcgOSA2LjEwNDU3IDkgNUM5IDMuODk1NDMgOC4xMDQ1NyAzIDcgM0M1Ljg5NTQzIDMgNSAzLjg5NTQzIDUgNUM1IDYuMTA0NTcgNS44OTU0MyA3IDcgN1oiIHN0cm9rZT0iIzAwMDAwMCIgc3Ryb2tlLXdpZHRoPSIyLjIiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCI+PC9wYXRoPjxwYXRoIGQ9Ik03IDIxQzguMTA0NTcgMjEgOSAyMC4xMDQ2IDkgMTlDOSAxNy44OTU0IDguMTA0NTcgMTcgNyAxN0M1Ljg5NTQzIDE3IDUgMTcuODk1NCA1IDE5QzUgMjAuMTA0NiA1Ljg5NTQzIDIxIDcgMjFaIiBzdHJva2U9IiMwMDAwMDAiIHN0cm9rZS13aWR0aD0iMi4yIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPjwvcGF0aD48cGF0aCBkPSJNNyA3VjE3IiBzdHJva2U9IiMwMDAwMDAiIHN0cm9rZS13aWR0aD0iMi4yIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPjwvcGF0aD48cGF0aCBkPSJNMTcgN1Y4QzE3IDEwLjUgMTUgMTEgMTUgMTFMOSAxM0M5IDEzIDcgMTMuNSA3IDE2VjE3IiBzdHJva2U9IiMwMDAwMDAiIHN0cm9rZS13aWR0aD0iMi4yIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiPjwvcGF0aD48L3N2Zz4=")
}
</style>

<style scoped>
.VPVersionSwitcher {
display: flex;
align-items: center;
}
.icon {
padding: 8px;
}
.title {
padding: 0 24px 0 12px;
line-height: 32px;
font-size: 14px;
font-weight: 700;
color: var(--vp-c-text-1);
}
.VPScreenVersionSwitcher {
border-bottom: 1px solid var(--vp-c-divider);
height: 48px;
overflow: hidden;
transition: border-color 0.5s;
}
.VPScreenVersionSwitcher .items {
visibility: hidden;
}
.VPScreenVersionSwitcher.open .items {
visibility: visible;
}
.VPScreenVersionSwitcher.open {
padding-bottom: 10px;
height: auto;
}
.VPScreenVersionSwitcher.open .button {
padding-bottom: 6px;
color: var(--vp-c-brand-1);
}
.VPScreenVersionSwitcher.open .button-icon {
/*rtl:ignore*/
transform: rotate(45deg);
}
.VPScreenVersionSwitcher button .icon {
margin-right: 8px;
}
.button {
display: flex;
justify-content: space-between;
align-items: center;
padding: 12px 4px 11px 0;
width: 100%;
line-height: 24px;
font-size: 14px;
font-weight: 500;
color: var(--vp-c-text-1);
transition: color 0.25s;
}
.button:hover {
color: var(--vp-c-brand-1);
}
.button-icon {
transition: transform 0.25s;
}
.group:first-child {
padding-top: 0px;
}
.group+.group,
.group+.item {
padding-top: 4px;
}
</style>
45 changes: 38 additions & 7 deletions docs/.vitepress/config.js
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
import {withMermaid} from "vitepress-plugin-mermaid";
import defineVersionedConfig from 'vitepress-versioning-plugin'

// https://vitepress.dev/reference/site-config
export default withMermaid({
export default withMermaid(defineVersionedConfig({
mermaid: {
// refer https://mermaid.js.org/config/setup/modules/mermaidAPI.html#mermaidapi-configuration-defaults for options
},
Expand All @@ -22,6 +23,7 @@ export default withMermaid({
}
},
themeConfig: {
versionSwitcher: false,
// https://vitepress.dev/reference/default-theme-config
siteTitle: false,
logo: {
Expand All @@ -30,7 +32,15 @@ export default withMermaid({
alt: 'openrouteservice logo'
},
search: {
provider: 'local'
provider: 'local',
options: {
_render(src, env, md) {
const html = md.render(src, env)
if (env.frontmatter?.search === false) return ''
if (env.relativePath.startsWith('versions')) return ''
return html
}
}
},
outline: {
level: [2, 4]
Expand All @@ -50,16 +60,19 @@ export default withMermaid({
{text: 'Homepage', link: 'https://openrouteservice.org'},
{text: 'API Playground', link: 'https://openrouteservice.org/dev/#/api-docs'},
{text: 'Forum', link: 'https://ask.openrouteservice.org'},
{component: 'VersionSwitcher'}
],
// undocumented options for NotFound-Page
notFound: {
title: 'MAYBE YOU CLICKED AN OLD LINK?',
title: 'PAGE NOT FOUND',
quote: 'We recently reworked most of our documentation. You probably ended up here by clicking an old link somewhere, e.g. in the forum. Let us know how you got here and we\'ll fix it. Click the link below and check "Getting Started" - this will help you figure out where to find what you came for.',
linkText: 'Documentation Home',
quote: 'We recently introduced versioning for our documentation. You probably ended up here by changing the version - and this page doesn\'t exist in this version. Click the link below and check "Getting Started" - you will need to change the version again, though.',
linkText: 'Documentation Home - latest Version',
},
sidebar: [
sidebar: {
'/': [
{
text: 'Home', link: '/',
text: 'Home - v9.0.0', link: '/',
items: [
{text: 'Getting Started', link: '/getting-started'},
{
Expand Down Expand Up @@ -221,5 +234,23 @@ export default withMermaid({
footer: {
message: '<a href="https://openrouteservice.org/">openrouteservice</a> is part of <a href="https://heigit.org/">HeiGIT gGmbH</a> and Universität Heidelberg <a href="https://www.geog.uni-heidelberg.de/gis/index_en.html">GIScience</a> research group. | <a href="https://heigit.org/imprint/">Imprint</a>'
}
}
},

locales: {
root: {
label: 'English',
lang: 'en'
}
})
},

versioning: {
latestVersion: "v9.0.0 (latest)",
sidebars: {
processSidebarURLs: true,
sidebarPathResolver: (version) => `.vitepress/sidebars/versioned/${version}.json`,
sidebarUrlProcessor: (url, version) => url.startsWith("http") ? url : `/${version}${url}`
},
},

}, __dirname ))
Loading

0 comments on commit 083adbc

Please sign in to comment.