[website] added logic to version switcher

Author: ilyabrower

website/algoliaConfig.ts

@@ -1,7 +1,4 @@
 export const algoliaConfig = {
   appName: 'PDUJZB0TBK',
   openKey: '9ad1935d853b24ce3fe9c0039bcf7b40',
-  mainSearchIndexName: 'intergalactic-docs',
-  iconsSearchIndexName: 'intergalactic-docs-icons',
-  illustrationsSearchIndexName: 'intergalactic-docs-illustrations',
 };

website/algoliaIndexes.ts

@@ -0,0 +1,7 @@
+import { currentBuildVersion } from './docs/.vitepress/vite.config';
+
+export const algoliaIndexes = {
+  mainSearchIndexName: `${currentBuildVersion}_intergalactic-docs`,
+  iconsSearchIndexName: `${currentBuildVersion}_intergalactic-docs-icons`,
+  illustrationsSearchIndexName: `${currentBuildVersion}_intergalactic-docs-illustrations`,
+};

website/docs/.vitepress/buildHooks.ts

@@ -1,15 +1,19 @@
 import { createWriteStream } from 'fs';
-import { resolve as resolvePath } from 'path';
-import { SitemapStream } from 'sitemap';
-import { UserConfig, DefaultTheme } from 'vitepress';
 import fs from 'fs/promises';
+import { resolve as resolvePath } from 'path';
+
 import algoliasearch from 'algoliasearch';
 import parseMarkdownMetadata from 'parse-md';
+import { SitemapStream } from 'sitemap';
+import type { UserConfig, DefaultTheme } from 'vitepress';
+
+import { currentBuildVersion, LATEST } from './vite.config';
+import { algoliaConfig } from '../../algoliaConfig.js';
+import { algoliaIndexes } from '../../algoliaIndexes.js';
 import iconsList from '../style/icon/icons-list.js';
 import illustrationsList from '../style/illustration/illustrations-list.js';
 
 import 'dotenv/config';
-import { algoliaConfig } from '../../algoliaConfig.js';
 
 const excludeFromSearch = ['a11y-report'];
 
@@ -31,6 +35,10 @@ if (process.env.CI) {
   }
 }
 
+const BASE_URL = `https://developer.semrush.com/intergalactic/${
+  currentBuildVersion === LATEST ? '' : `${currentBuildVersion}/`
+}`;
+
 const sitemapLinks: { url: string; lastmod?: number }[] = [];
 const searchObjects: {
   objectID: number;
@@ -116,10 +124,7 @@ const transformHtml: UserConfig<DefaultTheme.Config>['transformHtml'] = async (
           objectID: objectId++,
           title: title,
           type: level,
-          url:
-            'https://developer.semrush.com/intergalactic/' +
-            pageData.relativePath.replace(/((^|\/)index)?\.md$/, '$2') +
-            `#${id}`,
+          url: BASE_URL + pageData.relativePath.replace(/((^|\/)index)?\.md$/, '$2') + `#${id}`,
           heading: true,
           hierarchy: { ...hierarchy },
           changelogPage: pageData.relativePath.includes('changelog'),
@@ -134,9 +139,7 @@ const transformHtml: UserConfig<DefaultTheme.Config>['transformHtml'] = async (
       title: metadata?.title ?? pageData.title,
       content: metadata?.title ?? pageData.title,
       type: 'content',
-      url:
-        'https://developer.semrush.com/intergalactic/' +
-        pageData.relativePath.replace(/((^|\/)index)?\.md$/, '$2'),
+      url: BASE_URL + pageData.relativePath.replace(/((^|\/)index)?\.md$/, '$2'),
       heading: false,
       hierarchy: { lvl0: hierarchy.lvl0, lvl1: hierarchy.lvl1 },
       changelogPage: pageData.relativePath.includes('changelog'),
@@ -147,7 +150,7 @@ const transformHtml: UserConfig<DefaultTheme.Config>['transformHtml'] = async (
 };
 const buildEnd: UserConfig<DefaultTheme.Config>['buildEnd'] = async ({ outDir }) => {
   const sitemap = new SitemapStream({
-    hostname: 'https://developer.semrush.com/intergalactic/',
+    hostname: BASE_URL,
   });
   const writeStream = createWriteStream(resolvePath(outDir, 'sitemap.xml'));
   sitemap.pipe(writeStream);
@@ -158,9 +161,9 @@ const buildEnd: UserConfig<DefaultTheme.Config>['buildEnd'] = async ({ outDir })
   if (process.env.CI) {
     // await fs.writeFile('search-index.json', JSON.stringify(searchObjects, null, 2));
     const client = algoliasearch(algoliaConfig.appName, process.env.ALGOLIA_SECRET_KEY!);
-    const mainSearchIndex = client.initIndex(algoliaConfig.mainSearchIndexName);
-    const iconsSearchIndex = client.initIndex(algoliaConfig.iconsSearchIndexName);
-    const illustrationsSearchIndex = client.initIndex(algoliaConfig.illustrationsSearchIndexName!);
+    const mainSearchIndex = client.initIndex(algoliaIndexes.mainSearchIndexName);
+    const iconsSearchIndex = client.initIndex(algoliaIndexes.iconsSearchIndexName);
+    const illustrationsSearchIndex = client.initIndex(algoliaIndexes.illustrationsSearchIndexName!);
 
     const iconsSearchObjects = iconsList.icons.map((o, i) => ({ objectID: i, ...o }));
     const illustrationsSearchObjects = illustrationsList.illustrations.map((o, i) => ({

website/docs/.vitepress/config.ts

@@ -1,21 +1,41 @@
 import 'dotenv/config';
 
+import { resolve as resolvePath } from 'path';
+
 import { defineConfig } from 'vitepress';
+
+import { buildHooks } from './buildHooks';
+import { figmaIcon } from './figma-icon';
 import { configureMarkdownIt } from './markdown-it-config';
-import { viteConfig } from './vite.config';
 import { sideBarConfig } from './sidebarConfig';
-import { buildHooks } from './buildHooks';
+import { viteConfig, currentBuildVersion, LATEST } from './vite.config';
 import { algoliaConfig } from '../../algoliaConfig';
-import { figmaIcon } from './figma-icon';
-import { resolve as resolvePath } from 'path';
+import { algoliaIndexes } from '../../algoliaIndexes';
 
+const availableVersions = (process.env.AVAILABLE_VERSIONS ?? '').split(',');
 const gtmKey = 'GTM-PP7RKT7';
 
+const links = availableVersions.filter((version) => {
+  return version !== currentBuildVersion;
+});
+
+let versions: any = null;
+
+if (links.length > 0) {
+  versions = {
+    currentVersion: currentBuildVersion,
+    items: links.reverse(),
+  };
+}
+
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
-  base: '/intergalactic/',
-  outDir: resolvePath(__dirname, 'dist/intergalactic/'),
-  title: 'Intergalactic',
+  base: viteConfig.base,
+  outDir: resolvePath(
+    __dirname,
+    `dist/intergalactic/${currentBuildVersion !== LATEST ? `${currentBuildVersion}/` : ''}`,
+  ),
+  title: 'Intergalactic Design System',
   description: 'Design System',
   markdown: {
     config(md) {
@@ -81,13 +101,17 @@ export default defineConfig({
       copyright: 'Copyright © 2023-present Powered by Semrush. All rights reserved.',
     },
     siteTitle: false,
+    notFound: {
+      quote:
+        'This page may not exist in this version or the URL might be incorrect. Please check your spelling or try a different documentation version.',
+    },
 
     search: {
       provider: 'algolia',
       options: {
         appId: algoliaConfig.appName,
         apiKey: algoliaConfig.openKey,
-        indexName: algoliaConfig.mainSearchIndexName,
+        indexName: algoliaIndexes.mainSearchIndexName,
         searchParameters: {
           attributesToRetrieve: [
             'hierarchy',
@@ -103,16 +127,15 @@ export default defineConfig({
       },
     },
     editLink: {
-      pattern: 'https://github.com/semrush/intergalactic/edit/master/website/docs/:path',
+      pattern: `https://github.com/semrush/intergalactic/edit/${currentBuildVersion}/website/docs/:path`,
       text: 'Edit this page on GitHub',
     },
+
+    // @ts-ignore. Need this for custom versions switcher
+    versions,
+
     // https://vitepress.dev/reference/default-theme-config
     nav: [
-      // {
-      //   text: 'Roadmap',
-      //   link: 'https://github.com/orgs/semrush/projects/3/views/2',
-      //   target: '_blank',
-      // },
       {
         text: 'Releases',
         link: 'https://github.com/semrush/intergalactic/releases',
@@ -131,12 +154,12 @@ export default defineConfig({
       {
         icon: 'github',
         link: 'https://github.com/semrush/intergalactic',
-        ariaLabel: 'Go to GitHub repository',
+        ariaLabel: 'GitHub repository',
       },
       {
         icon: { svg: figmaIcon },
         link: 'https://figma.com/@semrush',
-        ariaLabel: 'Go to Intergalactic Design System Figma libraries',
+        ariaLabel: 'Figma libraries',
       },
     ],
   },

website/docs/.vitepress/theme/DevportalLogo.vue

@@ -1,22 +1,26 @@
 <template>
-  <a href="https://developer.semrush.com/" class="devportal-logo" target="_blank"
-    aria-label="Go to Semrush Developer portal">
-    <img src="/devportal-logo.svg" width="30" height="30" class="devportal-logo" />
+  <a href="https://developer.semrush.com/" class="devportal-logo" target="_blank" aria-label="Developer home page">
+    <img src="/devportal-logo.svg" width="30" height="30" class="devportal-logo" alt="Semrush Developer portal" />
     Developer
   </a>
-  <a .href="homeUrl" class="title intergalactic-logo" aria-label="Go to Intergalactic Design System main page">
+  <a :href="link" class="title intergalactic-logo" aria-label="Intergalactic Design System home page">
     Intergalactic
   </a>
 </template>
 <script setup lang="ts">
-const homeUrl = process.env.NODE_ENV === 'development' ? '/' : '/intergalactic/';
 
-import { useRouter } from 'vitepress';
+import { useData, useRouter } from 'vitepress';
 import { onMounted, onUnmounted } from 'vue';
 import {
   initAmplitude, initGlobalEventsHandler, disposeGlobalEventsHandler
 } from './amplitude/amplitude'
 
+const latest = import.meta.env.VITE_LATEST;
+const { theme } = useData();
+const currentVersion = theme.value.versions.currentVersion;
+
+const link = latest === currentVersion ? '/intergalactic/' : `/intergalactic/${currentVersion}/`
+
 onMounted(() => {
   const router = useRouter();
   initAmplitude();

website/docs/.vitepress/theme/Page404.vue

@@ -1,9 +1,9 @@
 <template>
-  <OriginalNotFoundPate></OriginalNotFoundPate>
+  <OriginalNotFoundPage></OriginalNotFoundPage>
 </template>
 
 <script setup>
-import OriginalNotFoundPate from 'vitepress/dist/client/theme-default/NotFound.vue'
+import OriginalNotFoundPage from 'vitepress/dist/client/theme-default/NotFound.vue'
 import { onMounted } from 'vue';
 import { logEvent } from './amplitude/amplitude';
 

website/docs/.vitepress/theme/VPNavBarMenu.vue

@@ -1,17 +1,60 @@
 <script lang="ts" setup>
-import { useData } from 'vitepress'
+import { watch, ref, onMounted, onUnmounted } from 'vue'
+import { useData, useRouter } from 'vitepress';
 import VPNavBarMenuLink from 'vitepress/dist/client/theme-default/components/VPNavBarMenuLink.vue'
 import VPNavBarMenuGroup from 'vitepress/dist/client/theme-default/components/VPNavBarMenuGroup.vue'
 import VPFlyout from 'vitepress/dist/client/theme-default/components/VPFlyout.vue'
 import PreferenceSwitch from './PreferenceSwitch.vue';
 import { preferSemcoreUi } from './preferences'
 
-const { theme } = useData()
+const latest = import.meta.env.VITE_LATEST;
+const versionSwitcherSettings = ref<null | {text: string, items: any[]}>(null);
+
+const { theme, page } = useData()
+const router = useRouter()
+
+const handleHashChange = () => {
+  versionSwitcherSettings.value = getSwitcher();
+};
+
+onMounted(() => {
+  versionSwitcherSettings.value = getSwitcher();
+  window.addEventListener('hashchange', handleHashChange);
+});
+onUnmounted(() => {
+  window.removeEventListener('hashchange', handleHashChange);
+});
+
+watch(() => page.value, () => {
+  versionSwitcherSettings.value = getSwitcher();
+});
+
+function getSwitcher() {
+  const origin = typeof window !== 'undefined' ? window.location.origin : '';
+  const hash = typeof window !== 'undefined' ? window.location.hash : '';
+  const currentVersion = theme.value.versions.currentVersion;
+  const path = router.route.path.split('/');
+  const isVersion = /v[0-9]+\.[0-9]+\.[0-9]+/.test(path[2]);
+
+  return {
+    text: currentVersion,
+    items: theme.value.versions.items.map((v: string) => {
+      const link = `${origin}/intergalactic/${v === latest ? '' : `${v}/`}${path.slice(isVersion ? 3 : 2).join('/')}${hash}`;
+
+      return {
+        text: v,
+        target: '_blank',
+        link,
+      }
+    }),
+  }
+}
 </script>
 
 <template>
   <nav v-if="theme.nav" aria-labelledby="main-nav-aria-label" class="VPNavBarMenu">
     <span id="main-nav-aria-label" class="visually-hidden">Main Navigation</span>
+    <VPNavBarMenuGroup v-if="versionSwitcherSettings" :item="versionSwitcherSettings" />
     <template v-for="item in theme.nav" :key="item.text">
       <VPNavBarMenuLink v-if="'link' in item" :item="item" />
       <VPNavBarMenuGroup v-else :item="item" />

website/docs/.vitepress/theme/VPNavScreenMenu.vue

@@ -0,0 +1,70 @@
+<script lang="ts" setup>
+import VPNavScreenMenuLink from 'vitepress/dist/client/theme-default/components/VPNavScreenMenuLink.vue'
+import VPNavScreenMenuGroup from 'vitepress/dist/client/theme-default/components/VPNavScreenMenuGroup.vue'
+import VPNavScreenMenuGroupSection from 'vitepress/dist/client/theme-default/components/VPNavScreenMenuGroupSection.vue'
+import { watch, ref, onMounted, onUnmounted } from 'vue'
+import { useData, useRouter } from 'vitepress';
+
+const latest = import.meta.env.VITE_LATEST;
+const versionSwitcherSettings = ref<null | {readonly text: string, readonly items: any[]}>(null);
+
+const { theme, page } = useData()
+const router = useRouter()
+
+const handleHashChange = () => {
+  versionSwitcherSettings.value = getSwitcher();
+};
+
+onMounted(() => {
+  versionSwitcherSettings.value = getSwitcher()
+  window.addEventListener('hashchange', handleHashChange)
+})
+onUnmounted(() => {
+  window.removeEventListener('hashchange', handleHashChange)
+})
+
+watch(() => page.value, () => {
+  versionSwitcherSettings.value = getSwitcher();
+});
+
+function getSwitcher() {
+  const origin = typeof window !== 'undefined' ? window.location.origin : '';
+  const hash = typeof window !== 'undefined' ? window.location.hash : '';
+  const currentVersion = theme.value.versions.currentVersion;
+  const path = router.route.path.split('/');
+  const isVersion = /v[0-9]+\.[0-9]+\.[0-9]+/.test(path[2]);
+
+  return {
+    text: currentVersion,
+    items: theme.value.versions.items.map((v: string) => {
+      const link = `${origin}/intergalactic/${v === latest ? '' : `${v}/`}${path.slice(isVersion ? 3 : 2).join('/')}${hash}`;
+
+      return {
+        text: v,
+        target: '_blank',
+        link,
+      }
+    }),
+  }
+}
+</script>
+
+<template>
+  <nav v-if="theme.nav" class="VPNavScreenMenu">
+    <VPNavScreenMenuGroupSection v-if="versionSwitcherSettings" :text="versionSwitcherSettings.text" :items="versionSwitcherSettings.items" />
+    <template v-for="item in theme.nav" :key="JSON.stringify(item)">
+      <VPNavScreenMenuLink v-if="'link' in item" :item="item" />
+      <component
+          v-else-if="'component' in item"
+          :is="item.component"
+          v-bind="item.props"
+          screen-menu
+      />
+      <VPNavScreenMenuGroup
+          v-else
+          :text="item.text || ''"
+          :items="item.items"
+      />
+    </template>
+  </nav>
+</template>