docs: link to all "available" versions of the docs

.github/workflows/build_documentation.yml

@@ -50,23 +50,54 @@ jobs:
         run: |
           set -ex
 
+          # A list of all doc versions to be built,
+          # (Written to versions.json)
+          echo '
+            [
+              {
+                "branch": "main",
+                "nixpkgsBranch": "nixos-unstable"
+              },
+              {
+                "branch": "nixos-24.05",
+                "nixpkgsBranch": "nixos-24.05",
+                "subPath": "stable"
+                // TODO: consider having 24.05 instead of stable?
+              }
+            ]
+          ' | sed 's/^ *\/\/.*//' | jq \
+              --arg repoName "$repoName" \
+              'map(
+                  .
+                  # Ensure subPath is a string
+                  | .subPath = (.subPath // "")
+                  # Construct baseHref from $repoName and .subPath
+                  | .baseHref = (
+                       .subPath
+                       | if . == "" then "" else "/\(.)" end
+                       | $repoName + .
+                       | "/\(.)/"
+                  )
+              )' > versions.json
+
           # 1: branch
-          # 2: install dir (relative to /nixvim/)
+          # 2: baseHref
+          # 3: install dir
           build() {
-            branch="$1"
-            dir="${2:+/$2}"
-            flakeref="github:${repo}${branch:+/$branch}"
-            baseHref="/${repoName}${dir}/"
-            installDir="${out}${dir}"
+            flakeref="github:${repo}${1:+/$1}"
+            baseHref="$2"
+            installDir="${out}${3:+/$3}"
 
-            # Build docs for the given flake ref, overriding baseHref in the derivation args
+            # Build docs for the given flake ref, overriding the relevant derivation args
             nix build --impure \
                 --argstr flakeref "$flakeref" \
                 --argstr baseHref "$baseHref" \
+                --arg-from-file versionsJson versions.json \
                 --expr '
                   {
                     flakeref,
                     baseHref,
+                    versionsJson,
                     system ? builtins.currentSystem,
                   }:
                   let
@@ -75,6 +106,7 @@ jobs:
                   in
                   packages.docs.override {
                     inherit baseHref;
+                    availableVersions = builtins.fromJSON versionsJson;
                   }
                 '
 
@@ -83,12 +115,16 @@ jobs:
             cp -r result/share/doc/* "$installDir"
           }
 
-          # Install main-branch docs at the top-level
-          build 'main' ''
+          # For each version of the docs...
+          jq -c '.[]' versions.json |
+          while IFS=$"\n" read -r entry; do
+              branch=$(echo "$entry" | jq -r '.branch')
+              baseHref=$(echo "$entry" | jq -r '.baseHref')
+              installDir=$(echo "$entry" | jq -r '.subPath')
 
-          # Install 24.05 docs under 'stable'
-          # TODO: consider having `<release>` instead of `stable`
-          build 'nixos-24.05' 'stable'
+              # Build this version of the docs
+              build "$branch" "$baseHref" "$installDir"
+          done
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

docs/mdbook/default.nix

@@ -1,5 +1,6 @@
 {
   pkgs,
+  runCommand,
   lib,
   modules,
   helpers,
@@ -8,6 +9,9 @@
   hmOptions,
   # The root directory of the site
   baseHref ? "/",
+  # A list of all available docs that should be linked to
+  # Each element should contain { branch; nixpkgsBranch; baseHref; }
+  availableVersions ? [ ],
 }:
 with lib;
 let
@@ -229,6 +233,46 @@ let
     ) docs.modules;
   };
 
+  # Zip the list of attrs into an attr of lists, for use as bash arrays
+  zippedVersions =
+    assert lib.assertMsg
+      (lib.all (o: o ? branch && o ? nixpkgsBranch && o ? baseHref) availableVersions)
+      ''
+        Expected all "availableVersions" docs entries to contain { branch, nixpkgsBranch, baseHref } attrs!
+      '';
+    lib.zipAttrs availableVersions;
+
+  docs-versions =
+    runCommand "docs-versions"
+      {
+        __structuredAttrs = true;
+        branches = zippedVersions.branch or [ ];
+        nixpkgsBranches = zippedVersions.nixpkgsBranch or [ ];
+        baseHrefs = zippedVersions.baseHref or [ ];
+        current = baseHref;
+      }
+      ''
+        touch "$out"
+        for i in ''${!branches[@]}; do
+          branch="''${branches[i]}"
+          nixpkgs="''${nixpkgsBranches[i]}"
+          baseHref="''${baseHrefs[i]}"
+          linkText="\`$branch\` branch"
+
+          link=
+          suffix=
+          if [ "$baseHref" = "$current" ]; then
+            # Don't bother linking to ourselves
+            link="$linkText"
+            suffix=" _(this page)_"
+          else
+            link="[$linkText]($baseHref)"
+          fi
+
+          echo "- The $link, for use with nixpkgs \`$nixpkgs\`$suffix" >> "$out"
+        done
+      '';
+
   prepareMD = ''
     # Copy inputs into the build directory
     cp -r --no-preserve=all $inputs/* ./
@@ -249,6 +293,10 @@ let
     substituteInPlace ./SUMMARY.md \
       --replace-fail "@NIXVIM_OPTIONS@" "$(cat ${pkgs.writeText "nixvim-options-summary.md" mdbook.nixvimOptions})"
 
+    # Patch index.md
+    substituteInPlace ./index.md \
+      --replace-fail "@DOCS_VERSIONS@" "$(cat ${docs-versions})"
+
     substituteInPlace ./modules/hm.md \
       --replace-fail "@HM_OPTIONS@" "$(cat ${mkMDDoc hmOptions})"
   '';

docs/mdbook/index.md

@@ -1,5 +1,13 @@
 # NixVim - A Neovim configuration system for nix
 
+## Other versions of these docs
+
+Please ensure you are referencing documentation that corresponds to the Nixvim version you are using!
+
+Documentation is currently available for the following versions:
+
+@DOCS_VERSIONS@
+
 ## What is it?
 NixVim is a [Neovim](https://neovim.io) distribution built around
 [Nix](https://nixos.org) modules. It is distributed as a Nix flake, and