docs

docs/user_guide/announcements.rst

@@ -15,6 +15,7 @@ By default, the value of your ``html_theme_options["announcement"]`` will be ins
 For example, the following configuration adds a simple announcement.
 
 .. code-block:: python
+   :caption: conf.py
 
    html_theme_options = {
       ...
@@ -33,8 +34,35 @@ If the value of ``html_theme_options["announcement"]`` begins with **``http``**
 For example, the following configuration tells the theme to load the ``custom-template.html`` example from this documentation's GitHub repository:
 
 .. code-block:: python
+   :caption: conf.py
 
    html_theme_options = {
       ...
       "announcement": "https://github.com/pydata/pydata-sphinx-theme/raw/main/docs/_templates/custom-template.html",
    }
+
+Version warning banners
+-----------------------
+
+In addition to the general-purpose announcement banner, the theme includes a built-in banner to warn users when they are viewing versions of your docs other than the latest stable version. To use this feature, add the following to your ``conf.py``:
+
+.. code-block:: python
+    :caption: conf.py
+
+    html_theme_options = {
+        ...
+        "show_version_warning_banner": True,
+    }
+.. warning::
+
+    This functionality relies on the :ref:`version switcher <version-dropdowns>` to determine the version number of the latest stable release.
+    *It will only work* if your version switcher ``.json`` has exactly one entry with property ``"preferred": true``
+    and a ``name`` property that begins with a version string that is parsable by the `compare-versions node module <https://www.npmjs.com/package/compare-versions>`__, for example:
+
+    .. code-block:: json
+
+        {
+            "name": "9.9.9 (current)",
+            "version": "stable",
+            "url": "https://anything"
+        }

docs/user_guide/version-dropdown.rst

@@ -1,3 +1,5 @@
+.. _version-dropdowns:
+
 Version switcher dropdowns
 ==========================