Fixes to "staying on the same page functionality"

The new implementation should be very flexible.

Fixes #7226

Additionally, this allows using the version switcher even if the website is published at a different URL than the `site_url`. In particular, the version switcher should now work locally when serving the site with `mike serve`.

The tests should demonstrate correctness of the implementation.

Author: ilyagr

docs/setup/setting-up-versioning.md

@@ -64,7 +64,6 @@ MkDocs implements this behavior by default, but there are a few caveats:
 - the [`site_url`][mkdocs.site_url] must be set correctly in `mkdocs.yml`.
   See the ["Publishing a new version"](#publishing-a-new-version) section for
   an example.
-- you must be viewing the site at that URL (and not locally, for example).
 - the redirect happens via JavaScript and there is no way to know which page you
   will be redirected to ahead of time.
 

src/templates/assets/javascripts/integrations/version/correspondingPage.test.ts

@@ -2,7 +2,7 @@ import { strict as assert } from "assert"
 
 import { Sitemap } from "../sitemap"
 
-import { selectedVersionCorrespondingURL } from "./correspondingPage"
+import { selectedVersionCorrespondingURL, shortestCommonPrefix, stripPrefix } from "./correspondingPage"
 
 describe("Version switcher tests", () => {
   // These examples are obtained by pausing the JS debugger in various situation and
@@ -54,7 +54,7 @@ describe("Version switcher tests", () => {
       "https://test.github.io/project/latest/foo/"
     ]
 
-    it("does not (yet, TODO #7226) return a URL when the selected version has the current page", () => {
+    it("returns a URL when the selected version has the current page", () => {
       assert.equal(
         selectedVersionCorrespondingURL({
           selectedVersionSitemap: sitemapFromURLList(sitemapURLsLatestVersion),
@@ -64,7 +64,7 @@ describe("Version switcher tests", () => {
           currentLocation: new URL("https://test.github.io/project/0.2/bar/#heading?param=some"),
           currentBaseURL: "https://test.github.io/project/0.2/"
         })?.href,
-        undefined,
+        "https://test.github.io/project/0.1/bar/#heading?param=some",
       )
     })
     it("returns nothing when the selected version does not have the current page", () => {
@@ -92,15 +92,15 @@ describe("Version switcher tests", () => {
       "https://localhost/project/0.1/foo/"
     ]
 
-    it("does not (yet, TODO) return a URL when the selected version has the current page", () => {
+    it("returns a URL when the selected version has the current page", () => {
       assert.equal(
         selectedVersionCorrespondingURL({
           selectedVersionSitemap: sitemapFromURLList(sitemapURLsLocalhost),
           selectedVersionBaseURL: new URL("https://localhost:8000/0.1/"),
           currentLocation: new URL("https://localhost:8000/0.2/bar/#heading?param=some"),
           currentBaseURL: "https://localhost:8000/0.2/"
         })?.href,
-        undefined,
+        "https://localhost:8000/0.1/bar/#heading?param=some",
       )
     })
     it("returns nothing when the selected version does not have the current page", () => {
@@ -130,3 +130,16 @@ describe("Version switcher tests", () => {
 function sitemapFromURLList(urls: string[]): Sitemap {
   return new Map(urls.map(url => [url, [new URL(url)]]))
 }
+
+describe("Utility string processing function tests", () => {
+  it("shortestCommonPrefix", () => {
+    assert.equal(shortestCommonPrefix([]), "")
+    assert.equal(shortestCommonPrefix(["abc", "abcd", "abe"]), "ab")
+    assert.equal(shortestCommonPrefix(["abcef", "abcd", "abc"]), "abc")
+    assert.equal(shortestCommonPrefix(["", "abc"]), "")
+  })
+  it("stripPrefix", () => {
+    assert.equal(stripPrefix("abc", "ab"), "c")
+    assert.equal(stripPrefix("abc", "b"), undefined)
+  })
+})

src/templates/assets/javascripts/integrations/version/correspondingPage.ts

@@ -27,11 +27,79 @@ export function selectedVersionCorrespondingURL(
     currentLocation,
     currentBaseURL}: CorrespondingURLParams
 ): URL | undefined {
-  const result = currentLocation.href.replace(
-    currentBaseURL,
-    selectedVersionBaseURL.href,
-  )
-  return selectedVersionSitemap.has(result.split("#")[0])
-    ? new URL(result)
-    : undefined
+  const current_path = (new URL(currentBaseURL)).pathname
+  const currentRelativePath = stripPrefix(currentLocation.pathname, current_path)
+  if (currentRelativePath === undefined) {
+    return
+  }
+  const sitemapCommonPrefix = shortestCommonPrefix(selectedVersionSitemap.keys())
+  if (!selectedVersionSitemap.has(sitemapCommonPrefix)) {
+    // We could also check that `commonSitemapPrefix` ends in the canonical version,
+    // similarly to https://github.com/squidfunk/mkdocs-material/pull/7227. However,
+    // I don't believe that Mike/MkDocs ever generate sitemaps where it would matter
+    return
+  }
+
+  const potentialSitemapURL = new URL(currentRelativePath, sitemapCommonPrefix)
+  if (!selectedVersionSitemap.has(potentialSitemapURL.href)) {
+    return
+  }
+
+  const result = new URL(currentRelativePath, selectedVersionBaseURL)
+  result.hash = currentLocation.hash
+  result.search = currentLocation.search
+  return result
+}
+
+// Basic string manipulation
+
+/**
+ *
+ * @param s - string
+ * @param prefix - prefix to strip
+ *
+ * @returns either the string with the prefix stripped or undefined if the
+ * string did not begin with the prefix.
+ */
+export function stripPrefix(s: string, prefix: string): string | undefined {
+  if (s.startsWith(prefix)) {
+    return s.slice(prefix.length)
+  }
+  return undefined
+}
+
+/**
+ *
+ * @param s1 - first string
+ * @param s2 - second string
+ *
+ * @returns - the length of the longest common prefix of the two strings.
+ */
+function commonPrefixLen(s1: string, s2: string): number {
+  const max = Math.min(s1.length, s2.length)
+  let result
+  for (result = 0; result < max; ++result) {
+    if (s1[result] !== s2[result]) {
+      break
+    }
+  }
+  return result
+}
+
+/**
+ *
+ * @param strs - an iterable of strings
+ *
+ * @returns the longest common prefix of all the strings
+ */
+export function shortestCommonPrefix(strs: Iterable<string>): string {
+  let result  // Undefined if no iterations happened
+  for (const s of strs) {
+    if (result === undefined) {
+      result = s
+    } else {
+      result = result.slice(0, commonPrefixLen(result, s))
+    }
+  }
+  return result ?? ""
 }