EnergySystemsModellingLab · AdrianDAlessandro · Jun 12, 2026 · Jun 16, 2026 · Jun 16, 2026 · Jun 16, 2026
diff --git a/.gitignore b/.gitignore
@@ -185,3 +185,6 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# Generated documentation theme file
+theme/header.hbs
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,13 +37,13 @@ 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:
+old: header
     @# Clean output dir
     @rm -rf book/release
 

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
@@ -10,7 +10,6 @@
 
 from release import get_releases
 
-DOCS_SITE_ROOT = "https://energysystemsmodellinglab.github.io/MUSE2"
 REPO_ROOT = Path(__file__).parent.parent.absolute()
 DOCS_DIR = REPO_ROOT / "docs"
 
@@ -72,15 +71,12 @@ def build_docs_for_release(release: str, repo_path: Path, outdir: Path) -> None:
     # Apply patches, if any
     apply_patches_for_release(release, release_path)
 
+    # Copy current theme into the release worktree so theme is consistent
+    shutil.copytree(REPO_ROOT / "theme", release_path / "theme", dirs_exist_ok=True)
+
     # 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}")
@@ -98,7 +94,7 @@ def build_old_docs() -> None:
         clone_repo_to(repo_path)
 
         # Generate documentation for each previous release
-        for release in get_releases():
+        for i, release in enumerate(get_releases()):
             build_docs_for_release(release, repo_path, outdir)
 
 

diff --git a/docs/generate_header.py b/docs/generate_header.py
@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+#
+# 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_header_hbs() -> None:
+    """Write the theme/header.hbs file."""
+    theme_dir = REPO_ROOT / "theme"
+    theme_dir.mkdir(parents=True, exist_ok=True)
+    path = theme_dir / "header.hbs"
+    print(f"Writing {path}")
+    env = Environment(loader=FileSystemLoader(DOCS_DIR / "templates"))
+    template = env.get_template("header.hbs.jinja")
+    releases = [
+        {"label": release, "stable": i == 0} for i, release in enumerate(get_releases())
+    ]
+    out = template.render(releases=releases)
+
+    with path.open("w", encoding="utf-8") as f:
+        f.write(out)
+
+
+if __name__ == "__main__":
+    generate_header_hbs()
diff --git a/docs/generate_versions_docs.py b/docs/generate_versions_docs.py
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,169 @@
+<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: pointer;
+  }
+
+  #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" role="status" aria-live="polite"></div>
+
+<div id="version-widget">
+  <ul id="version-list" aria-label="Documentation versions"></ul>
+  <span id="version-label" tabindex="0" role="button" aria-haspopup="listbox" aria-controls="version-list">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 versionMatch = /\/release\/(v[\d.]+)\//.exec(path);
+    var isDev = !versionMatch;
+    var currentVersion = isDev ? "development" : versionMatch[1];
+    var isStable = false;
+
+    // Build version list
+    var pathToRoot = "{% raw %}{{path_to_root}}{% endraw %}";
+    var versions = [
+      { label: "development", stable: false },
+{%- for release in releases %}
+      { label: "{{ release.label }}", stable: {{ release.stable|lower }} },
+{%- endfor %}
+    ];
+
+    function hrefFor(label) {
+      if (isDev) {
+        if (label === "development") return pathToRoot;
+        return pathToRoot + "release/" + label + "/index.html";
+      }
+      // Old versioned docs (e.g. /release/v2.0.0/)
+      if (label === "development") return pathToRoot + "../../index.html";
+      return pathToRoot + "../" + label + "/index.html";
+    }
+
+    versions.forEach(function (v) {
+      var li = document.createElement("li");
+
+      versionLabel = v.stable ? v.label + " (stable)" : v.label;
+
+      if (v.label === currentVersion) {
+        // Determine if current version is the stable release
+        isStable = v.stable;
+        // Set widget label
+        labelText.textContent = versionLabel;
+
+        var strong = document.createElement("strong");
+        strong.textContent = versionLabel;
+        li.appendChild(strong);
+      } else {
+        var a = document.createElement("a");
+        a.href = hrefFor(v.label);
+        a.textContent = versionLabel;
+        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