From 3b59085a664b628dfea34c965d7dec8a3eb22b75 Mon Sep 17 00:00:00 2001
From: Blaž Hrastnik <blaz@mxxn.io>
Date: Tue, 23 Jun 2026 08:23:06 +0000
Subject: [PATCH] book: Make the stable vs nightly docs distinction clearer

---
 book/book.toml | 2 +-
 book/custom.css | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 book/version.js | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 book/src/title-page.md | 12 ++++++++++--
 4 file(s) changed, 130 insertion(s)(+), 3 deletion(s)(-)

diff --git a/book/book.toml b/book/book.toml
--- a/book/book.toml
+++ b/book/book.toml
@@ -10,7 +10,7 @@
 git-repository-url = "https://github.com/helix-editor/helix"
 edit-url-template = "https://github.com/helix-editor/helix/edit/master/book/{path}"
 additional-css = ["custom.css"]
-additional-js = ["ts-query.js"]
+additional-js = ["ts-query.js", "version.js"]
 
 [output.html.search]
 use-boolean-and = true
diff --git a/book/custom.css b/book/custom.css
--- a/book/custom.css
+++ b/book/custom.css
@@ -263,3 +263,64 @@
 :where(.colibri) .hljs-strong {
   font-weight: 700;
 }
+
+#helix-version-banner {
+  margin: 0 0 1.75rem;
+  padding: .75rem 1.15rem;
+  border-radius: 4px;
+  border-inline-start: 4px solid var(--blockquote-warning-color, #efba5d);
+  background-color: var(--quote-bg);
+  font-size: .95em;
+  line-height: 1.55;
+}
+
+#helix-version-banner.archived {
+  border-inline-start-color: var(--blockquote-note-color, #697C81);
+}
+
+#helix-version-banner a {
+  white-space: nowrap;
+  font-weight: 500;
+}
+
+.version-tiles {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  gap: 1rem;
+  margin: 1.75rem 0 2rem;
+}
+
+.version-tiles .version-tile,
+.version-tiles .version-tile:hover {
+  text-decoration: none;
+}
+
+.version-tiles .version-tile {
+  --tile-accent: var(--blockquote-tip-color, #a4a0e8);
+  display: block;
+  padding: 1.25rem 1.4rem;
+  border: 1px solid var(--table-border-line, hsla(201, 20%, 92%, .2));
+  border-radius: 8px;
+  background-color: var(--quote-bg, rgba(0, 0, 0, .2));
+  color: inherit;
+  transition: border-color .15s ease, background-color .15s ease;
+}
+
+.version-tiles .version-tile:hover,
+.version-tiles .version-tile.current {
+  border-color: var(--tile-accent);
+  background-color: color-mix(in srgb, var(--tile-accent) 9%, var(--quote-bg, transparent));
+}
+
+.version-tiles .version-tile strong {
+  display: block;
+  margin-bottom: .25rem;
+  font-size: 1.15em;
+  font-weight: 600;
+  color: var(--heading-fg);
+}
+
+.version-tiles .version-tile .version-tile-sub {
+  opacity: .8;
+  font-size: .9em;
+}
diff --git a/book/version.js b/book/version.js
new file mode 100644
--- /dev/null
+++ b/book/version.js
@@ -0,0 +1,58 @@
+// Version banner + landing-page tile highlighting.
+//
+// The site hosts several channels under one domain:
+//   /            latest stable release (a copy of the newest /<version>/)
+//   /master/     development docs, rebuilt on every push to master
+//   /<version>/  archived release snapshots
+//
+// CI deploys the same built HTML to each folder, so the channel can only
+// be told apart at runtime from the URL path.
+(function () {
+  "use strict";
+
+  var segments = window.location.pathname.split("/").filter(Boolean);
+  var first = segments[0];
+
+  var channel;
+  if (first === "master") {
+    channel = { kind: "nightly" };
+  } else if (/^\d+\.\d+/.test(first || "")) {
+    channel = { kind: "version", version: first };
+  } else {
+    channel = { kind: "stable" };
+  }
+
+  if (channel.kind === "nightly" || channel.kind === "version") {
+    var releasePath = "/" + segments.slice(1).join("/");
+
+    var banner = document.createElement("div");
+    banner.id = "helix-version-banner";
+    banner.setAttribute("role", "status");
+
+    var link =
+      '<a href="' + releasePath + '">View this page in the latest release &rarr;</a>';
+    if (channel.kind === "nightly") {
+      banner.className = "nightly";
+      banner.innerHTML =
+        "You're reading the <strong>development (master)</strong> docs &mdash; " +
+        "they describe unreleased changes. " + link;
+    } else {
+      banner.className = "archived";
+      banner.innerHTML =
+        "You're reading the docs for <strong>" + channel.version +
+        "</strong>, which may be outdated. " + link;
+    }
+
+    var main = document.querySelector("#mdbook-content main") || document.body;
+    main.insertBefore(banner, main.firstChild);
+  }
+
+  // Landing-page chooser
+  var currentHref = channel.kind === "nightly" ? "/master/" : "/";
+  var tiles = document.querySelectorAll(".version-tiles .version-tile");
+  for (var i = 0; i < tiles.length; i++) {
+    if (tiles[i].getAttribute("href") === currentHref) {
+      tiles[i].classList.add("current");
+    }
+  }
+})();
diff --git a/book/src/title-page.md b/book/src/title-page.md
--- a/book/src/title-page.md
+++ b/book/src/title-page.md
@@ -1,7 +1,15 @@
 # Helix
 
-Docs for bleeding edge master can be found at
-[https://docs.helix-editor.com/master](https://docs.helix-editor.com/master).
+<div class="version-tiles">
+  <a class="version-tile" href="/">
+    <strong>Stable</strong>
+    <span class="version-tile-sub">Documentation for the latest tagged release.</span>
+  </a>
+  <a class="version-tile" href="/master/">
+    <strong>Latest (master)</strong>
+    <span class="version-tile-sub">Bleeding-edge docs built from the <code>master</code> branch.</span>
+  </a>
+</div>
 
 See the [usage] section for a quick overview of the editor, [keymap]
 section for all available keybindings and the [configuration] section

--
tangled.sh