EnergySystemsModellingLab · AdrianDAlessandro · Jun 17, 2026 · Jun 17, 2026 · Jun 17, 2026 · Jun 17, 2026
diff --git a/build-docs.just b/build-docs.just
@@ -2,7 +2,7 @@
 export RUSTDOCFLAGS := "-D warnings"
 
 # Build all documentation, except old docs
-all: cli-help file-format examples versions book api
+all: cli-help file-format examples header book api
 
 # Build all documentation, including old docs
 all_with_old: all old
@@ -37,10 +37,10 @@ examples:
     @echo Building docs for examples
     @uv run docs/generate_example_docs.py
 
-# Build TOC for old versions
-versions:
-    @echo Building TOC for old versions of documentation
-    @uv run docs/generate_versions_docs.py
+# Generate theme file for version banner and widget for docs
+header:
+    @echo Generating theme/header.hbs
+    @uv run docs/generate_header.py
 
 # Build documentation for previous releases
 old:

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1,4 +1,3 @@
 # Generated documentation files
 command_line_help.md
 examples.md
-versions.md
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -25,4 +25,3 @@
   - [MUSE2 v2.0.0 (October 14, 2025)](release_notes/v2.0.0.md)
   - [MUSE2 v2.1.0 (March 31, 2026)](release_notes/v2.1.0.md)
   - [Next unreleased version](release_notes/upcoming.md)
-- [Other versions of documentation](versions.md)
diff --git a/docs/build_old_docs.py b/docs/build_old_docs.py
@@ -78,12 +78,6 @@ def build_docs_for_release(release: str, repo_path: Path, outdir: Path) -> Path:
     # Build docs
     sp.run(("just", f"{release_path!s}/build-docs"), check=True)
 
-    # Patch versions.html to redirect to main versions page
-    with (release_path / "book" / "versions.html").open("w", encoding="utf-8") as f:
-        f.write(f"""<head>
-    <meta http-equiv="Refresh" content="0; URL={DOCS_SITE_ROOT}/versions.html" />
-</head>""")
-
     # Move to output directory
     release_outdir = outdir / release
     print(f"Copying to {release_outdir}")

diff --git a/docs/generate_versions_docs.py → docs/generate_header.py b/docs/generate_versions_docs.py → docs/generate_header.py
@@ -1,26 +1,27 @@
 #!/usr/bin/env python3
 #
-# A script to generate the versions.md file, listing links to old versions of documentation.
+# A script to generate theme/header.hbs from a Jinja2 template.
 
 from pathlib import Path
 
 from jinja2 import Environment, FileSystemLoader
 from release import get_releases
 
 DOCS_DIR = Path(__file__).parent.absolute()
+REPO_ROOT = DOCS_DIR.parent
 
 
-def generate_versions_md() -> None:
-    """Write the versions.md file."""
-    path = DOCS_DIR / "versions.md"
+def generate_header_hbs() -> None:
+    """Write the theme/header.hbs file."""
+    path = REPO_ROOT / "theme" / "header.hbs"
     print(f"Writing {path}")
     env = Environment(loader=FileSystemLoader(DOCS_DIR / "templates"))
-    template = env.get_template("versions.md.jinja")
+    template = env.get_template("header.hbs.jinja")
     out = template.render(releases=get_releases())
 
     with path.open("w", encoding="utf-8") as f:
         f.write(out)
 
 
 if __name__ == "__main__":
-    generate_versions_md()
+    generate_header_hbs()
diff --git a/docs/release/patches/v2.0.0/0002-Add-placeholder-other-versions-of-docs-chapter.patch b/docs/release/patches/v2.0.0/0002-Add-placeholder-other-versions-of-docs-chapter.patch
diff --git a/docs/release/patches/v2.1.0/0001-Remove-other-versions-docs-from-contents.patch b/docs/release/patches/v2.1.0/0001-Remove-other-versions-docs-from-contents.patch
@@ -0,0 +1,20 @@
+From 2ee8d44b2c4a6b3b2e5ed1a546a3dd6ac2c20dab Mon Sep 17 00:00:00 2001
+From: Adrian D'Alessandro <a.dalessandro@imperial.ac.uk>
+Date: Wed, 17 Jun 2026 18:59:07 +0100
+Subject: [PATCH] Remove other versions docs from contents
+
+---
+ docs/SUMMARY.md | 1 -
+ 1 file changed, 1 deletion(-)
+
+diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
+index 38e09211..36f0c2ee 100644
+--- a/docs/SUMMARY.md
++++ b/docs/SUMMARY.md
+@@ -25,4 +25,3 @@
+   - [MUSE2 v2.0.0 (October 14, 2025)](release_notes/v2.0.0.md)
+   - [MUSE2 v2.1.0 (March 31, 2026)](release_notes/v2.1.0.md)
+   - [Next unreleased version](release_notes/upcoming.md)
+-- [Other versions of documentation](versions.md)
+--
+2.50.1 (Apple Git-155)
diff --git a/docs/templates/header.hbs.jinja b/docs/templates/header.hbs.jinja
@@ -0,0 +1,173 @@
+<style>
+  :root { --banner-height: 36px; }
+
+  #version-banner {
+    display: none;
+    position: fixed;
+    top: 0; left: 0; right: 0;
+    height: var(--banner-height);
+    z-index: 9999;
+    align-items: center;
+    justify-content: center;
+    font-size: 0.875em;
+    box-sizing: border-box;
+    padding: 0 16px;
+  }
+
+  #version-widget {
+    position: fixed;
+    bottom: 0;
+    right: 1rem;
+    z-index: 9999;
+    font-size: 0.85em;
+    font-family: sans-serif;
+  }
+
+  #version-widget:hover #version-list,
+  #version-widget:focus-within #version-list {
+    max-height: 300px;
+  }
+
+  #version-widget:hover #version-arrow,
+  #version-widget:focus-within #version-arrow {
+    transform: rotate(180deg);
+  }
+
+  #version-label {
+    display: block;
+    background: #0c3547;
+    color: #fff;
+    padding: 6px 12px;
+    border-radius: 4px 4px 0 0;
+    cursor: default;
+    user-select: none;
+  }
+
+  #version-arrow {
+    display: inline-block;
+    transition: transform 0.2s ease;
+  }
+
+  #version-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    background: #fff;
+    color: #222;
+    border: 1px solid #ccc;
+    border-bottom: none;
+    max-height: 0;
+    overflow: hidden;
+    transition: max-height 0.2s ease;
+  }
+
+  #version-list li {
+    padding: 6px 12px;
+    white-space: nowrap;
+    border-bottom: 1px solid #eee;
+  }
+
+  #version-list a {
+    color: #0c3547;
+    text-decoration: none;
+  }
+
+  #version-list a:hover {
+    text-decoration: underline;
+  }
+</style>
+
+<div id="version-banner"></div>
+
+<div id="version-widget">
+  <ul id="version-list"></ul>
+  <span id="version-label">docs: <span id="version-label-text"></span> <span id="version-arrow">&#x25b2;</span></span>
+</div>
+
+<script>
+  (function () {
+    var path = window.location.pathname;
+    var banner = document.getElementById("version-banner");
+    var labelText = document.getElementById("version-label-text");
+    var list = document.getElementById("version-list");
+
+    var isStable = /\/release\/stable\//.test(path);
+    var versionMatch = /\/release\/(v[\d.]+)\//.exec(path);
+    var isDev = !isStable && !versionMatch;
+    var currentVersion = isDev ? "development" : isStable ? "stable" : versionMatch[1];
+
+    // Set widget label
+    labelText.textContent = currentVersion;
+
+    // Build version list
+    var pathToRoot = "{% raw %}{{path_to_root}}{% endraw %}";
+    var versions = [
+      { label: "development" },
+      { label: "stable" },
+{%- for release in releases %}
+      { label: "{{ release }}" },
+{%- endfor %}
+    ];
+
+    function hrefFor(label) {
+      if (isDev) {
+        if (label === "development") return pathToRoot;
+        if (label === "stable") return pathToRoot + "release/stable/index.html";
+        return pathToRoot + "release/" + label + "/index.html";
+      }
+
+      if (isStable) {
+        if (label === "development") return pathToRoot + "../../index.html";
+        if (label === "stable") return pathToRoot;
+        return pathToRoot + "../" + label + "/index.html";
+      }
+
+      // Old versioned docs (e.g. /release/v2.0.0/)
+      if (label === "development") return pathToRoot + "../../index.html";
+      if (label === "stable") return pathToRoot + "../stable/index.html";
+      return pathToRoot + "../" + label + "/index.html";
+    }
+
+    versions.forEach(function (v) {
+      var li = document.createElement("li");
+      if (v.label === currentVersion) {
+        li.innerHTML = "<strong>" + v.label + "</strong>";
+      } else {
+        var a = document.createElement("a");
+        a.href = hrefFor(v.label);
+        a.textContent = v.label;
+        li.appendChild(a);
+      }
+      list.appendChild(li);
+    });
+
+    // Banner (not shown for stable)
+    if (isStable) return;
+
+    if (isDev) {
+      banner.innerHTML =
+        "This is the <strong>\u00a0development version\u00a0</strong> of the MUSE2 documentation. " +
+        "For older releases, use the version selector in the bottom right corner of this page.";
+      banner.style.backgroundColor = "#fff3cd";
+      banner.style.borderBottom = "1px solid #ffc107";
+      banner.style.color = "#664d03";
+    } else {
+      var version = versionMatch[1];
+      banner.innerHTML =
+        "You are viewing docs for <strong>\u00a0" + version + "\u00a0</strong> of MUSE2. " +
+        "For newer releases, use the version selector in the bottom right corner of this page.";
+      banner.style.backgroundColor = "#f8d7da";
+      banner.style.borderBottom = "1px solid #f5c2c7";
+      banner.style.color = "#842029";
+    }
+
+    banner.style.display = "flex";
+
+    var s = document.createElement("style");
+    s.textContent =
+      "body { padding-top: var(--banner-height); }" +
+      "#mdbook-menu-bar.sticky { top: var(--banner-height) !important; }" +
+      "#mdbook-sidebar { top: var(--banner-height) !important; height: calc(100vh - var(--banner-height)) !important; }";
+    document.head.appendChild(s);
+  })();
+</script>
diff --git a/docs/templates/versions.md.jinja b/docs/templates/versions.md.jinja
diff --git a/theme/.gitignore b/theme/.gitignore
@@ -0,0 +1,2 @@
+# Generated documentation theme file
+header.hbs
diff --git a/theme/header.hbs b/theme/header.hbs
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		# Generated documentation theme file
		header.hbs