Merge 77b37cb9a9 into d28e05af87

assets/js/versions.template.js

@@ -0,0 +1,96 @@
+/*
+Copyright 2025 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// This oddity is an attempt at producing a readable Hugo template while avoiding
+// JS syntax errors in your IDE
+const currentVersion = `{{ if eq .Site.Params.version.status "unstable" }}
+    {{- /**/ -}}
+    unstable
+    {{- /**/ -}}
+{{ else }}
+    {{- /**/ -}}
+    {{ printf "v%s.%s" .Site.Params.version.major .Site.Params.version.minor }}
+    {{- /**/ -}}
+{{ end }}`;
+
+function appendVersion(parent, name, url) {
+    // The list item
+    const li = document.createElement("li");
+    if (name === currentVersion) {
+        li.classList.add("selected")
+    }
+    if (name === "unstable") {
+        li.classList.add("unstable")
+    }
+    parent.appendChild(li);
+
+    // The link
+    const a = document.createElement("a");
+    a.classList.add("dropdown-item")
+    a.setAttribute("href", url);
+    li.appendChild(a);
+
+    // Handle clicks manually to preserve the current path / fragment
+    a.addEventListener("click", (ev) => {
+        // If the URL is a relative link (i.e. the historical versions changelog), just
+        // let the browser load it
+        if (url.startsWith("/")) {
+            return;
+        }
+
+        // Stop further event handling
+        ev.preventDefault();
+        ev.stopPropagation();
+
+        // Try to find the current version segment
+        const href = window.location.href;
+        const matches = href.match(/\/unstable\/|\/latest\/|\/v\d+.\d+\//g);
+        if (!matches) {
+            window.location.href = url;
+            return;
+        }
+
+        // Replace the segment
+        window.location.href = href.replace(matches[0], `/${name}/`);
+    });
+
+    // The link text
+    const text = document.createTextNode(name);
+    a.appendChild(text);
+}
+
+// TODO: Load /latest/versions.json
+fetch("/versions.json")
+    .then(r => r.json())
+    .then(versions => {
+        // Find the surrounding list element
+        const ul = document.querySelector("ul#version-selector");
+        if (!ul) {
+            console.error("Cannot populate version selector: ul element not found");
+            return;
+        }
+
+        // Add an entry for the unstable version
+        appendVersion(ul, "unstable", "https://spec.matrix.org/unstable");
+
+        // Add an entry for each proper version
+        for (const version of versions) {
+            appendVersion(ul, version.name, `https://spec.matrix.org/${version.name}`);
+        }
+
+        // For historical versions, simply link to the changelog
+        appendVersion(ul, "historical", '{{ (site.GetPage "changelog/historical").RelPermalink }}');
+    });

assets/scss/_styles_project.scss

@@ -50,6 +50,20 @@ Custom SCSS for the Matrix spec
   a {
     color: $black;
   }
+
+  /* Make the version dropdown scroll if its too large */
+  ul#version-selector {
+    max-height: 80vh;
+    overflow-y: auto;
+  }
+
+  ul#version-selector li.selected a {
+    color: $secondary;
+  }
+
+  ul#version-selector li.unstable:not(.selected) a {
+    color: $warning;
+  }
 }
 
 /* Styles for the sidebar nav */

changelogs/internal/newsfragments/2256.clarification

@@ -0,0 +1 @@
+Add version picker in the navbar.

config/_default/hugo.toml

@@ -78,6 +78,10 @@ current_version_url = "https://spec.matrix.org/latest"
 # major = "1"
 # minor = "16"
 
+[[params.versions]]
+# We must include this parameter to enable docsy's version picker in the navbar. The picker
+# is populated automatically in navbar-version-selector.html.
+
 # User interface configuration
 [params.ui]
 # Collapse HTTP API and event <details> elements

layouts/_partials/hooks/body-end.html

@@ -8,3 +8,10 @@
 */}}
 {{ $toc := resources.Get "js/toc.js" -}}
 <script defer src="{{ $toc.RelPermalink }}"></script>
+
+{{- /* Load the versions script template, run and publish it */ -}}
+{{ with resources.Get "js/versions.template.js" }}
+  {{ with resources.ExecuteAsTemplate "js/versions.js" $ . }}
+    <script defer src="{{ .RelPermalink }}"></script>
+  {{ end }}
+{{ end }}

layouts/_partials/navbar-version-selector.html

@@ -0,0 +1,18 @@
+{{- /*
+
+  A version of the navbar-version-selector.html partial in Docsy,
+  modified to read the versions from /versions.json.
+
+*/ -}}
+
+{{ $changelog := site.GetPage "changelog" }}
+{{ $pages := $changelog.RegularPages.ByDate.Reverse }}
+
+<div class="dropdown">
+    <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+        All Versions
+    </a>
+    <ul class="dropdown-menu" id="version-selector">
+        {{- /* The menu is built by versions.template.js */ -}}
+    </ul>
+</div>

layouts/docs/baseof.html

@@ -5,6 +5,25 @@
 
 */}}
 
+{{/* Generate a static file versions.json that can be used to populate the version picker */}}
+{{ if .IsHome }}
+  {{- /* Load all changelog subpages, sorted by release date */ -}}
+  {{ $changelog := site.GetPage "changelog" }}
+  {{ $pages := $changelog.RegularPages.ByDate.Reverse }}
+
+  {{- /* Collect proper versions and build metadata dicts */ -}}
+  {{ $versions := slice }}
+  {{ range $pages }}
+    {{ if findRE `^v[0-9]+\.[0-9]+$` .Params.linkTitle }}
+      {{ $versions = $versions | append (dict "name" .Params.linkTitle "date" .Params.date ) }}
+    {{ end }}
+  {{ end }}
+
+  {{- /* Generate the JSON */ -}}
+  {{ $json := jsonify $versions }}
+  {{ $noop := (resources.FromString "/versions.json" $json).Permalink }}
+{{ end }}
+
 <!doctype html>
 <html itemscope itemtype="http://schema.org/WebPage"
     {{- with .Site.Language.LanguageDirection }} dir="{{ . }}" {{- end -}}