Preserve page anchor when moving between versions

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+* The version selector now also preserves the anchor (hash) when switching between documentation versions. Additionally, the outdated/dev version warning banner now also tries to keep you on the same page (and position) when linking to the latest stable release. ([#2880])
 * Added `Remotes.Forgejo` for specifying a `Remote` hosted on a Forgejo instance (such as codeberg.org). ([#2857])
 * Doctests now default to the `parser_for_module` of the module that the docstring appears in, allowing modules that set their syntax version via `Base.Experimental.@set_syntax_version` to have their doctests parsed with the correct syntax automatically. Also added support for `DocTestSyntax` metadata and per-block `syntax=` attributes to explicitly specify a syntax version. ([#2874])
 

assets/html/js/versions.js

@@ -47,18 +47,21 @@ $(document).ready(function () {
     // construct the target URL with the same page path
     var target_url = target_href;
     if (page_path && page_path !== "" && page_path !== "index.html") {
-      // remove trailing slash from target_href if present
-      if (target_url.endsWith("/")) {
-        target_url = target_url.slice(0, -1);
+      // ensure target_href ends with a slash before appending page path
+      if (!target_url.endsWith("/")) {
+        target_url = target_url + "/";
       }
-      target_url = target_url + "/" + page_path;
+      target_url = target_url + page_path;
     }
 
+    // preserve the anchor (hash) from the current page
+    var current_hash = window.location.hash;
+
     // check if the target page exists, fallback to homepage if it doesn't
     fetch(target_url, { method: "HEAD" })
       .then(function (response) {
         if (response.ok) {
-          window.location.href = target_url;
+          window.location.href = target_url + current_hash;
         } else {
           // page doesn't exist in the target version, go to homepage
           window.location.href = target_href;

assets/html/warner.js

@@ -37,7 +37,40 @@ function maybeAddWarning() {
   closer.addEventListener("click", function () {
     document.body.removeChild(div);
   });
-  const href = window.documenterBaseURL + "/../" + window.DOCUMENTER_STABLE;
+  var target_href =
+    window.documenterBaseURL + "/../" + window.DOCUMENTER_STABLE;
+
+  // try to stay on the same page when linking to the stable version
+  // get the current page path relative to the version root
+  var current_page = window.location.pathname;
+
+  // resolve the documenterBaseURL to an absolute path
+  // documenterBaseURL is a relative path (usually "."), so we need to resolve it
+  var base_url_absolute = new URL(documenterBaseURL, window.location.href)
+    .pathname;
+  if (!base_url_absolute.endsWith("/")) {
+    base_url_absolute = base_url_absolute + "/";
+  }
+
+  // extract the page path after the version directory
+  // e.g., if we're on /stable/man/guide.html, we want "man/guide.html"
+  var page_path = "";
+  if (current_page.startsWith(base_url_absolute)) {
+    page_path = current_page.substring(base_url_absolute.length);
+  }
+
+  // construct the target URL with the same page path
+  var target_url = target_href;
+  if (page_path && page_path !== "" && page_path !== "index.html") {
+    // ensure target_href ends with a slash before appending page path
+    if (!target_url.endsWith("/")) {
+      target_url = target_url + "/";
+    }
+    target_url = target_url + page_path;
+  }
+
+  // preserve the anchor (hash) from the current page
+  var current_hash = window.location.hash;
 
   // Determine if this is a development version or an older release
   let warningMessage = "";
@@ -51,12 +84,35 @@ function maybeAddWarning() {
       "This documentation is for an <strong>older version</strong> that may be missing recent changes.<br>";
   }
 
-  warningMessage +=
-    '<a href="' +
-    href +
-    '">Click here to go to the documentation for the latest stable release.</a>';
+  // Create the link element with same-page navigation
+  const link = document.createElement("a");
+  link.href = target_url + current_hash;
+  link.textContent =
+    "Click here to go to the documentation for the latest stable release.";
+
+  // If we're trying to stay on the same page, verify it exists first
+  if (page_path && page_path !== "" && page_path !== "index.html") {
+    link.addEventListener("click", function (e) {
+      e.preventDefault();
+      // check if the target page exists, fallback to homepage if it doesn't
+      fetch(target_url, { method: "HEAD" })
+        .then(function (response) {
+          if (response.ok) {
+            window.location.href = target_url + current_hash;
+          } else {
+            // page doesn't exist in the target version, go to homepage
+            window.location.href = target_href;
+          }
+        })
+        .catch(function (error) {
+          // network error or other failure - use homepage
+          window.location.href = target_href;
+        });
+    });
+  }
 
   div.innerHTML = warningMessage;
+  div.appendChild(link);
   div.appendChild(closer);
   document.body.appendChild(div);
 }