[BACKPORT 4.4] docs(feature): Version switcher from single source (#14963)

.github/workflows/docs_deploy.yml

@@ -43,7 +43,7 @@ jobs:
 
       - name: Upload artifact
         if: ${{ github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.merged) }}
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: qgc_docs_build
           path: docs/.vitepress/dist/
@@ -56,7 +56,7 @@ jobs:
 
     steps:
       - name: Download Artifact
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: qgc_docs_build
           path: ~/_book

docs/.vitepress/config.mjs

@@ -1,14 +1,23 @@
 const getSidebar = require("./get_sidebar.js");
 import { defineConfig } from "vitepress";
+import navbarData from "./navbar.json";
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
-  title: "QGC Guide (4.4)",
+  title: process.env.BRANCH_NAME
+    ? `QGC Guide (${process.env.BRANCH_NAME})`
+    : "QGC Guide",
   description:
     "How to use and develop QGroundControl for PX4 or ArduPilot powered vehicles.",
   ignoreDeadLinks: true, // Do this for stable, where we don't yet have all translations
   base: process.env.BRANCH_NAME ? "/" + process.env.BRANCH_NAME + "/" : "",
 
+  vite: {
+    ssr: {
+      noExternal: ["vp-dynamic-nav"],
+    },
+  },
+
   head: [
     [
       "script",
@@ -77,88 +86,9 @@ export default defineConfig({
       provider: "local",
     },
 
-    nav: [
-      {
-        text: "QGroundControl",
-        items: [
-          {
-            text: "Website",
-            link: "http://qgroundcontrol.com/",
-            ariaLabel: "QGC website link",
-          },
-          {
-            text: "Source Code",
-            link: "https://github.com/mavlink/qgroundcontrol",
-          },
-          {
-            text: "Docs Source Code",
-            link: "https://github.com/mavlink/qgroundcontrol/tree/master/doc",
-          },
-        ],
-      },
-      {
-        text: "Flight Stacks",
-        items: [
-          {
-            text: "PX4",
-            link: "https://docs.px4.io/en/",
-            ariaLabel: "PX4 docs link",
-          },
-          {
-            text: "ArduPilot",
-            link: "http://ardupilot.org",
-            ariaLabel: "ArduPilot site link",
-          },
-        ],
-      },
-      {
-        text: "Dronecode",
-        items: [
-          {
-            text: "PX4",
-            link: "https://px4.io/",
-            ariaLabel: "PX4 website link",
-          },
-          {
-            text: "QGroundControl",
-            link: "http://qgroundcontrol.com/",
-          },
-          {
-            text: "MAVSDK",
-            link: "https://mavsdk.mavlink.io/",
-          },
-          {
-            text: "MAVLINK",
-            link: "https://mavlink.io/en/",
-          },
-          {
-            text: "Dronecode Camera Manager",
-            link: "https://camera-manager.dronecode.org/en/",
-          },
-        ],
-      },
-      {
-        text: "Support",
-        link: "https://docs.qgroundcontrol.com/master/en/support/support.html",
-      },
-      {
-        text: "Version",
-        items: [
-          {
-            text: "master",
-            link: "https://docs.qgroundcontrol.com/master/en/",
-          },
-          {
-            text: "v4.3",
-            link: "https://docs.qgroundcontrol.com/Stable_V4.3/en/",
-          },
-          {
-            text: "v4.4",
-            link: "https://docs.qgroundcontrol.com/Stable_V4.4/en/",
-          },
-        ],
-      },
-    ],
+    dynamicNavUrl:
+      "https://raw.githubusercontent.com/mavlink/qgroundcontrol/master/docs/.vitepress/navbar.json",
+    dynamicNavInitial: navbarData.nav,
 
     socialLinks: [
       { icon: "github", link: "https://github.com/mavlink/qgroundcontrol" },

docs/.vitepress/navbar.json

@@ -0,0 +1,99 @@
+{
+  "nav": [
+    {
+      "text": "QGroundControl",
+      "items": [
+        {
+          "text": "Website",
+          "link": "http://qgroundcontrol.com/",
+          "ariaLabel": "QGC website link"
+        },
+        {
+          "text": "Download QGC (stable)",
+          "link": "https://docs.qgroundcontrol.com/master/en/qgc-user-guide/getting_started/download_and_install.html",
+          "ariaLabel": "Download stable QGC"
+        },
+        {
+          "text": "Download QGC (daily build)",
+          "link": "https://docs.qgroundcontrol.com/master/en/qgc-user-guide/releases/daily_builds.html",
+          "ariaLabel": "Download stable QGC"
+        },
+        {
+          "text": "Source Code",
+          "link": "https://github.com/mavlink/qgroundcontrol"
+        },
+        {
+          "text": "Docs Source Code",
+          "link": "https://github.com/mavlink/qgroundcontrol/tree/master/docs"
+        }
+      ]
+    },
+    {
+      "text": "Flight Stacks",
+      "items": [
+        {
+          "text": "PX4",
+          "link": "https://docs.px4.io/en/",
+          "ariaLabel": "PX4 docs link"
+        },
+        {
+          "text": "ArduPilot",
+          "link": "http://ardupilot.org",
+          "ariaLabel": "ArduPilot site link"
+        }
+      ]
+    },
+    {
+      "text": "Dronecode",
+      "items": [
+        {
+          "text": "PX4",
+          "link": "https://px4.io/",
+          "ariaLabel": "PX4 website link"
+        },
+        {
+          "text": "QGroundControl",
+          "link": "http://qgroundcontrol.com/"
+        },
+        {
+          "text": "MAVSDK",
+          "link": "https://mavsdk.mavlink.io/"
+        },
+        {
+          "text": "MAVLINK",
+          "link": "https://mavlink.io/en/"
+        },
+        {
+          "text": "Dronecode Camera Manager",
+          "link": "https://camera-manager.dronecode.org/en/"
+        }
+      ]
+    },
+    {
+      "text": "Support",
+      "link": "https://docs.qgroundcontrol.com/master/en/qgc-user-guide/support/support.html"
+    },
+    {
+      "text": "Version",
+      "preservePath": true,
+      "items": [
+        {
+          "text": "master",
+          "link": "https://docs.qgroundcontrol.com/master/en/"
+        },
+        {
+          "text": "v5.1",
+          "link": "https://docs.qgroundcontrol.com/Stable_V5.1/en/"
+        },
+        {
+          "text": "v5.0",
+          "link": "https://docs.qgroundcontrol.com/Stable_V5.0/en/"
+        },
+        {
+          "text": "v4.4",
+          "link": "https://docs.qgroundcontrol.com/Stable_V4.4/en/"
+        }
+      ]
+    }
+  ]
+}

docs/.vitepress/theme/components/VersionToast.vue

@@ -0,0 +1,87 @@
+<script setup>
+import { onMounted, ref } from "vue";
+import { useData, inBrowser } from "vitepress";
+
+const DISPLAY_MS = 2000;
+
+const { site } = useData();
+const visible = ref(false);
+const message = ref("");
+
+// Layout mounts once per real page load and persists across in-session SPA
+// navigation, so this fires once per hard load/refresh, never per page view.
+onMounted(() => {
+  if (!inBrowser) return;
+
+  message.value = `Now viewing ${site.value.title}`;
+  visible.value = true;
+  setTimeout(() => {
+    visible.value = false;
+  }, DISPLAY_MS);
+});
+</script>
+
+<template>
+  <Transition name="version-toast-fade">
+    <div v-if="visible" class="version-toast vp-doc" role="status">
+      <h1>{{ message }}</h1>
+      <button
+        class="version-toast-close"
+        aria-label="Dismiss"
+        @click="visible = false"
+      >
+        &times;
+      </button>
+    </div>
+  </Transition>
+</template>
+
+<style scoped>
+.version-toast {
+  position: fixed;
+  top: 33vh;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  z-index: 90;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 24px;
+  width: 90vw;
+  max-width: 688px; /* matches VitePress's default doc content column width */
+  padding: 24px 32px;
+  /* Opaque page-surface base with the theme's translucent warning tint
+     layered on top, so the tint stays theme-adaptive without looking washed out. */
+  background-color: var(--vp-c-bg);
+  background-image: linear-gradient(var(--vp-c-warning-soft), var(--vp-c-warning-soft));
+  color: var(--vp-c-warning-1);
+  border-radius: 8px;
+  box-shadow: var(--vp-shadow-3);
+  text-align: center;
+}
+
+/* The "vp-doc" class on .version-toast makes this pick up VitePress's own
+   .vp-doc h1 font-size/line-height rule (including its responsive
+   breakpoint) instead of duplicating those numbers here. h1 margin is
+   already reset to 0 by VitePress's base.css. */
+
+.version-toast-close {
+  background: none;
+  border: none;
+  padding: 0;
+  color: inherit;
+  cursor: pointer;
+  font-size: 32px;
+  line-height: 1;
+}
+
+.version-toast-fade-enter-active,
+.version-toast-fade-leave-active {
+  transition: opacity 0.3s ease;
+}
+
+.version-toast-fade-enter-from,
+.version-toast-fade-leave-to {
+  opacity: 0;
+}
+</style>

docs/.vitepress/theme/index.js

@@ -3,14 +3,24 @@ import { h } from "vue";
 import DefaultTheme from "vitepress/theme";
 import "./style.css";
 
+// Toast shown once per page load, announcing the current docs version
+import VersionToast from "./components/VersionToast.vue";
+
+import { createDynamicNav, DynamicNav } from "vp-dynamic-nav";
+
 /** @type {import('vitepress').Theme} */
 export default {
-  extends: DefaultTheme,
-  Layout: () => {
-    return h(DefaultTheme.Layout, null, {
-      // https://vitepress.dev/guide/extending-default-theme#layout-slots
-    });
-  },
+  // createDynamicNav(DefaultTheme).Layout is a parameterless function that
+  // doesn't forward slots passed to it, so its nav-bar slots are reproduced
+  // here directly against DefaultTheme.Layout instead of nesting through it
+  // (nesting silently drops any slot we'd add, e.g. layout-top for the toast).
+  extends: createDynamicNav(DefaultTheme),
+  Layout: () =>
+    h(DefaultTheme.Layout, null, {
+      "nav-bar-content-before": () => h(DynamicNav),
+      "nav-screen-content-after": () => h(DynamicNav, { screen: true }),
+      "layout-top": () => h(VersionToast),
+    }),
   enhanceApp({ app, router, siteData }) {
     // ...
   },