NEW: Add version warning banners

docs/_static/switcher.json

@@ -2,11 +2,13 @@
   {
     "name": "dev",
     "version": "latest",
+    "description": "the development version",
     "url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/"
   },
   {
     "name": "0.9.0 (stable)",
     "version": "stable",
+    "preferred": "true",
     "url": "https://pydata-sphinx-theme.readthedocs.io/en/stable/"
   },
   {

docs/user_guide/configuring.rst

@@ -696,6 +696,49 @@ for more information). Example:
     }
 
 
+Add a warning banner for outdated versions
+------------------------------------------
+
+You can add a large warning banner to direct users to a specific version of your documentation if they are on a different version.
+This is useful if you have many versions of your documentation (e.g. old releases, development versions) and wish to direct users to a specific version (e.g., the latest stable version).
+
+To activate this feature, add ``"preferred": "true"`` to one of the entries in your ``switcher.json`` file.
+This will mark it as the "preferred version" that other versions should direct to.
+
+In addition, you may mark versions with a ``"description"`` which will be displayed in the banner message.
+If not given, the value of ``"description"`` will be ``"a previous release"``.
+
+For example, below we demonstrate a ``switcher.json`` with five entries: a development version, the latest release (which is preferred), a release candidate, and two previous releases.
+
+.. code:: json
+
+    [
+        {
+            "name": "v2.2dev0 (development)",
+            "version": "v2.2dev0",
+            "description": "a development version",
+            "url": "https://mysite.org/en/2.1/index.html"
+        },        {
+            "name": "v2.1 (stable)",
+            "version": "2.1",
+            "preferred": "true",
+            "url": "https://mysite.org/en/2.1/index.html"
+        },
+        {
+            "version": "2.1rc1",
+            "description": "a release candidate for 2.1"
+            "url": "https://mysite.org/en/2.1rc1/index.html"
+        },
+        {
+            "version": "2.0",
+            "url": "https://mysite.org/en/2.0/index.html"
+        },
+        {
+            "version": "1.0",
+            "url": "https://mysite.org/en/1.0/index.html"
+        }
+    ]
+
 Specify where to display the switcher
 -------------------------------------
 

src/pydata_sphinx_theme/assets/styles/index.scss

@@ -39,6 +39,8 @@ $grid-breakpoints: (
 @import "./sections/footer";
 @import "./sections/footer-article";
 @import "./sections/header";
+@import "./sections/header-version-warning";
+
 @import "./sections/sidebar-primary";
 @import "./sections/sidebar-secondary";
 

src/pydata_sphinx_theme/assets/styles/sections/_header-version-warning.scss

@@ -0,0 +1,34 @@
+/**
+ * A warning banner to direct users to a stable version of the documentation.
+ */
+.bd-header-version-warning {
+  position: relative; // So the background color variable fill works
+  padding: 1rem;
+
+  .bd-header-version-warning__content {
+    @include background-from-color-variable(--pst-color-danger, 0.2);
+    display: flex;
+    justify-content: center;
+    align-content: center;
+    gap: 1rem;
+    font-size: 1.2rem;
+
+    span {
+      margin: auto 0;
+      text-align: center;
+    }
+
+    // The button to the right of the banner text.
+    a {
+      z-index: 1; // To put it above the background banner.
+      button {
+        font-size: 1.2rem;
+        background-color: var(--pst-color-danger);
+        color: var(--pst-color-on-background);
+        &:active {
+          opacity: 0.8;
+        }
+      }
+    }
+  }
+}

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/version-switcher.html

@@ -43,6 +43,13 @@
         // Set empty strings by default so that these attributes exist and can be used in CSS selectors
         btn.dataset["activeVersionName"] = "";
         btn.dataset["activeVersion"] = "";
+
+        // The version of the current documentation page
+        let currentVersion = "{{ theme_switcher.get('version_match') }}";
+
+        // Grab entry for the current version so we use it later
+        let currentVersionEntry = data.filter(entry => entry.version == currentVersion)[0];
+
         // create links to the corresponding page in the other docs versions
         $.each(data, function(index, entry) {
             // if no custom name specified (e.g., "latest"), use version string
@@ -72,12 +79,34 @@
             // this version, rather than using sphinx's {{ version }} variable.
             // also highlight the dropdown entry for the currently-viewed
             // version's entry
-            if (entry.version == "{{ theme_switcher.get('version_match') }}") {
+            if (entry.version == currentVersion) {
                 node.classList.add("active");
                 btn.innerText = btn.dataset["activeVersionName"] = entry.name;
                 btn.dataset["activeVersion"] = entry.version;
             }
+
+            // If this entry is the one we wish to direct to
+            // And this entry is not currently active
+            // then add a banner to direct people there
+            if ((entry.preferred == "true") && (entry.version != currentVersion)) {
+                if (currentVersionEntry.description) {
+                    var currentVersionDescription = currentVersionEntry.description;
+                } else {
+                    var currentVersionDescription = "a previous release";
+                };
+                placeholder = document.getElementById("header-version-warning-placeholder");
+                placeholder.insertAdjacentHTML("afterend", `
+                <div class="bd-header-version-warning container-fluid" id="header-version-warning">
+                    <div class="bd-header-version-warning__content">
+                        <span>This documentation is for <strong>${currentVersionDescription}</strong>.</span>
+                        <a href="${entry.url}${currentFilePath}"><button class="btn">Switch to: ${entry.name}</button></a>
+                    </div>
+                </div>
+                `);
+                console.log("[PST]: Inserted version warning banner...");
+            }
         });
+
     });
 })();
 </script>

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/layout.html

@@ -32,6 +32,7 @@
       {%- include "sections/header.html" %}
     </nav>
     {% endblock %}
+    {% include "sections/version-warning.html" %}
 
     <div class="bd-container container-xl">
       <div class="bd-container__inner row">

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/sections/version-warning.html

@@ -0,0 +1,6 @@
+{# A placeholder for a version warning that will be replaced with a banner #}
+{# ref: components/version-switcher.html for JS that does this #}
+{%- if theme_switcher %}
+<!-- A placeholder we use to insert a version warning banner if a preferred version is specified. -->
+<div id="header-version-warning-placeholder"></div>
+{% endif -%}