Add "directory" versioning scheme, which permits versioned docs in one build.

Usage:
* Set `extra.version.provider: directory` in `mkdocs.yml`.
* Place versioned docs in subdirectories named after the version, e.g. `/v1.1/`, `/v1.2/`.
* Create a `.meta.yml` file in each version directory with version metadata, e.g.:
  ```yaml
  version: v1.2
  ```
* At the top level, create a `versions.json` file listing available versions, e.g.:
  ```json
  [
    {"version": "v1.2", title: "v1.2", "alias": "latest"},
    {"version": "v1.1", title: "v1.1"}
  ]
  ```

Signed-off-by: Evan Anderson <[email protected]>

Author: evankanderson

src/templates/assets/javascripts/_/index.ts

@@ -81,9 +81,10 @@ export type Translations =
  * Versioning
  */
 export interface Versioning {
-  provider: "mike"                     /* Version provider */
+  provider: "mike" | "directory"       /* Version provider */
   default?: string | string[]          /* Default version */
   alias?: boolean                      /* Show alias */
+  declared_version: string             /* Version info from multi-version builds */
 }
 
 /**

src/templates/assets/javascripts/bundle.ts

@@ -154,7 +154,7 @@ if (feature("navigation.instant"))
     .subscribe(document$)
 
 /* Set up version selector */
-if (config.version?.provider === "mike")
+if (config.version?.provider != undefined)
   setupVersionSelector({ document$ })
 
 /* Always close drawer and search on navigation */

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

@@ -82,10 +82,13 @@ export function setupVersionSelector(
     )
 
   /* Determine current version */
+  let [, current] = config.base.match(/([^/]+)\/?$/)!
+  if (config.version?.provider === "directory") {
+    current = config.version?.declared_version
+  }
   const current$ = versions$
     .pipe(
       map(versions => {
-        const [, current] = config.base.match(/([^/]+)\/?$/)!
         return versions.find(({ version, aliases }) => (
           version === current || aliases.includes(current)
         )) || versions[0]
@@ -95,10 +98,15 @@ export function setupVersionSelector(
   /* Intercept inter-version navigation */
   versions$
     .pipe(
-      map(versions => new Map(versions.map(version => [
-        `${new URL(`../${version.version}/`, config.base)}`,
-        version
-      ]))),
+      map(versions => new Map(versions.map(version => {
+        let versionPath = `../${version.version}/`
+        if (config.version?.provider === "directory") {
+          versionPath = `./${version.version}/`
+        }
+        return [
+          `${new URL(versionPath, config.base)}`,
+          version
+        ]}))),
       switchMap(urls => fromEvent<MouseEvent>(document.body, "click")
         .pipe(
           filter(ev => !ev.metaKey && !ev.ctrlKey),
@@ -129,16 +137,35 @@ export function setupVersionSelector(
             }
             return EMPTY
           }),
-          switchMap(selectedVersionBaseURL => {
-            return fetchSitemap(selectedVersionBaseURL).pipe(
+          withLatestFrom(current$),
+          switchMap(([selectedVersionBaseURL, current]) => {
+            let sitemapBase = selectedVersionBaseURL
+            let currentBase = config.base
+            if (config.version?.provider === "directory") {
+              sitemapBase = new URL(config.base)
+              currentBase = `${new URL(current.version, config.base)}/`
+            }
+            return fetchSitemap(sitemapBase).pipe(
               map(
-                sitemap =>
-                  selectedVersionCorrespondingURL({
+                sitemap => {
+                  if (config.version?.provider === "directory") {
+                    // "directory" provider will have all the versions in the same sitemap;
+                    // filter the sitemap to only URLs that are in the selected version.
+                    const filteredSitemap: typeof sitemap = new Map()
+                    for (const [url, links] of sitemap) {
+                      if (new URL(url).pathname.startsWith(selectedVersionBaseURL.pathname)) {
+                        filteredSitemap.set(url, links)
+                      }
+                    }
+                    sitemap = filteredSitemap
+                  }
+                  return selectedVersionCorrespondingURL({
                     selectedVersionSitemap: sitemap,
                     selectedVersionBaseURL,
                     currentLocation: getLocation(),
-                    currentBaseURL: config.base
-                  }) ?? selectedVersionBaseURL,
+                    currentBaseURL: currentBase
+                  }) ?? selectedVersionBaseURL
+                },
               ),
             )
           })

src/templates/base.html

@@ -394,9 +394,15 @@
 
       <!-- Versioning -->
       {%- if config.extra.version -%}
+        {%- if config.extra.version.provider == "mike" -%}
         {%- set mike = config.plugins.mike -%}
-        {%- if not mike or mike.config.version_selector -%}
-          {%- set _.version = config.extra.version -%}
+          {%- if not mike or mike.config.version_selector -%}
+            {%- set _.version = config.extra.version -%}
+          {%- endif -%}
+        {%- elif config.extra.version.provider == "directory" -%}
+          {%- if page and (page.meta.version) -%}
+            {%- set _.version = {"provider":"directory", "declared_version": page.meta.version | string} -%}
+          {%- endif -%}
         {%- endif -%}
       {%- endif -%}