From 748e4e5d8f1099171ca3e8e88d79168abb16a728 Mon Sep 17 00:00:00 2001
From: olalekan odukoya <odukoyaonline@gmail.com>
Date: Tue, 2 Dec 2025 00:18:29 +0100
Subject: [PATCH] add warning banner for unreleased branch or version in the
 documentation

Signed-off-by: olalekan odukoya <odukoyaonline@gmail.com>
---
 docs/overrides/main.html           | 155 +++++++++++++++++++++++++++++
 docs/overrides/stylesheets/crd.css |  13 +--
 docs/scripts/serve-docs.sh         |  12 ++-
 3 files changed, 173 insertions(+), 7 deletions(-)
 create mode 100644 docs/overrides/main.html

diff --git a/docs/overrides/main.html b/docs/overrides/main.html
new file mode 100644
index 00000000000..b0f5d7fcf75
--- /dev/null
+++ b/docs/overrides/main.html
@@ -0,0 +1,155 @@
+{% extends "base.html" %} {% block extrahead %} {{ super() }}
+<style>
+  #version-banner {
+    display: none;
+    position: sticky;
+    top: 0;
+    left: 0;
+    right: 0;
+    width: 100%;
+    background-color: #00bcd4;
+    color: white;
+    padding: 8px 16px;
+    text-align: center;
+    font-size: 14px;
+    line-height: 1.5;
+    z-index: 10000;
+    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+  }
+
+  #version-banner a {
+    color: white;
+    text-decoration: underline;
+    margin-left: 8px;
+  }
+
+  #version-banner a:hover {
+    text-decoration: none;
+  }
+
+  .md-header {
+    transition: top 0.2s ease;
+  }
+</style>
+
+<script>
+  (function () {
+    "use strict";
+
+    const CONFIG = {
+      UNRELEASED_VERSION: "main",
+      RETRY_DELAY: 500,
+      HEADER_ADJUST_DELAY: 100,
+    };
+
+    function getCurrentVersion() {
+      const path = window.location.pathname;
+      const versionMatch = path.match(/\/(main|v\d+\.\d+[^\/]*)/);
+      return versionMatch ? versionMatch[1] : null;
+    }
+
+    function getAvailableVersions() {
+      const versionList = document.querySelector("ul.md-version__list");
+      if (!versionList) return [];
+
+      const links = Array.from(
+        versionList.querySelectorAll("a.md-version__link")
+      );
+
+      return links
+        .map((link) => {
+          const href = link.href || link.getAttribute("href");
+          const match = href.match(/\/(v\d+\.\d+[^\/]*)\//);
+          return match ? match[1] : null;
+        })
+        .filter((v) => v && /^v\d+\.\d+/.test(v))
+        .filter((v, i, arr) => arr.indexOf(v) === i);
+    }
+
+    function getLatestVersionPath() {
+      const versions = getAvailableVersions();
+
+      const latestVersion = versions[0];
+      const currentPath = window.location.pathname;
+
+      return (
+        currentPath.replace(/\/main(\/|$)/, `/${latestVersion}$1`) ||
+        `/${latestVersion}/`
+      );
+    }
+
+    function createBanner() {
+      const banner = document.createElement("div");
+      banner.id = "version-banner";
+      banner.innerHTML = `
+    <strong>You are viewing the docs for an unreleased version.</strong>
+    <a href="#" id="latest-version-link">Click here to go to the latest stable version.</a>
+  `;
+
+      document.body.insertBefore(banner, document.body.firstChild);
+      banner.style.display = "block";
+
+      return banner;
+    }
+
+    function updateBannerLink(banner) {
+      const link = banner.querySelector("#latest-version-link");
+      if (!link) return;
+
+      const latestPath = getLatestVersionPath();
+      link.href = latestPath;
+    }
+
+    function adjustHeader(banner) {
+      setTimeout(() => {
+        const header = document.querySelector(".md-header");
+        if (!header) return;
+
+        const bannerHeight = banner.offsetHeight;
+        const headerHeight = header.offsetHeight;
+
+        header.style.top = `${bannerHeight}px`;
+        document.documentElement.style.setProperty(
+          "--md-header-height",
+          `${bannerHeight + headerHeight}px`
+        );
+        document.documentElement.style.setProperty(
+          "--md-scroll-margin",
+          `${bannerHeight + headerHeight}px`
+        );
+      }, CONFIG.HEADER_ADJUST_DELAY);
+    }
+
+    function init() {
+      const currentVersion = getCurrentVersion();
+
+      if (currentVersion !== CONFIG.UNRELEASED_VERSION) {
+        return;
+      }
+
+      const banner = createBanner();
+      updateBannerLink(banner);
+
+      setTimeout(() => updateBannerLink(banner), CONFIG.RETRY_DELAY);
+
+      adjustHeader(banner);
+    }
+
+    function waitForDOM() {
+      if (
+        document.readyState === "complete" ||
+        document.readyState === "interactive"
+      ) {
+        console.log("DOM is ready, initializing...");
+        init();
+        return;
+      }
+
+      console.log("DOM not ready yet, checking again...");
+      setTimeout(waitForDOM, 1000);
+    }
+
+    waitForDOM();
+  })();
+</script>
+{% endblock %}
diff --git a/docs/overrides/stylesheets/crd.css b/docs/overrides/stylesheets/crd.css
index 83b432def6c..f3eb87b9f6c 100644
--- a/docs/overrides/stylesheets/crd.css
+++ b/docs/overrides/stylesheets/crd.css
@@ -35,14 +35,13 @@ ul.crd-index {
   color: #fff;
 }
 
-
 dl.crd-meta {
   display: flex;
   flex-flow: row wrap;
   border-bottom: 1px solid #00000012;
 }
 
-[data-md-color-primary=black] dl.crd-meta {
+[data-md-color-primary="black"] dl.crd-meta {
   border-bottom: 1px solid #e6e6e612;
 }
 
@@ -62,13 +61,14 @@ dl.crd-meta {
   border-top: 1px solid #00000012;
 }
 
-[data-md-color-primary=black] .crd-meta dt, [data-md-color-primary=black] .crd-meta dd {
+[data-md-color-primary="black"] .crd-meta dt,
+[data-md-color-primary="black"] .crd-meta dd {
   border-top: 1px solid #e6e6e612;
 }
 
 .crd-meta a.version {
   font-family: var(--md-code-font-family);
-  font-size:
+  font-size: var(--md-code-font-size);
   margin-right: 10px;
 }
 
@@ -83,8 +83,9 @@ dl.crd-meta {
   margin-left: -0.1em;
 }
 
-.property-description, .property-meta {
-  margin: 5px 0
+.property-description,
+.property-meta {
+  margin: 5px 0;
 }
 
 .property-title {
diff --git a/docs/scripts/serve-docs.sh b/docs/scripts/serve-docs.sh
index f9c2857420b..e6fd1f1c509 100755
--- a/docs/scripts/serve-docs.sh
+++ b/docs/scripts/serve-docs.sh
@@ -34,7 +34,17 @@ fi
 # for local docs testing, we don't care what the remote branch looks like.
 MIKE_OPTIONS+=(--ignore-remote-status)
 
-mike set-default "${MIKE_OPTIONS[@]}" --allow-undefined main
+MIKE_OUTPUT=$(mike list "${MIKE_OPTIONS[@]}" 2>&1)
+
+VERSIONS=$(echo "$MIKE_OUTPUT" | grep -oE '^v[0-9]+\.[0-9]+' 2>/dev/null || true)
+
+if [[ -n "$VERSIONS" ]]; then
+  DEFAULT_VERSION=$(echo "$VERSIONS" | sort -V | tail -1 2>/dev/null || echo "main")
+else
+  DEFAULT_VERSION="main"
+fi
+
+mike set-default "${MIKE_OPTIONS[@]}" --allow-undefined "${DEFAULT_VERSION}"
 if [[ -n "${DEV_MODE:-}" ]]; then
   mkdocs serve --dev-addr=127.0.0.1:8000 --livereload
 else