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,12 +1,16 @@
 {
   pkgs,
+  runCommand,
   lib,
   evaledModules,
   nixosOptionsDoc,
   transformOptions,
   search,
   # 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 ? [ ],
 }:
 let
   inherit (evaledModules.config.meta) nixvimInfo;
@@ -269,6 +273,15 @@ let
       ) mdbook.wrapperOptions
     );
   };
+
+  # 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;
 in
 
 pkgs.stdenv.mkDerivation (finalAttrs: {
@@ -332,6 +345,10 @@ pkgs.stdenv.mkDerivation (finalAttrs: {
       --replace-fail "@PLATFORM_OPTIONS@" "$wrapperOptionsSummary" \
       --replace-fail "@NIXVIM_OPTIONS@" "$nixvimOptionsSummary"
 
+    # Patch index.md
+    substituteInPlace ./index.md \
+      --replace-fail "@DOCS_VERSIONS@" "$(cat ${finalAttrs.passthru.docs-versions})"
+
     mdbook build
     cp -r ./book/* $dest
     mkdir -p $dest/search
@@ -351,5 +368,35 @@ pkgs.stdenv.mkDerivation (finalAttrs: {
     search = search.override {
       baseHref = finalAttrs.baseHref + "search/";
     };
+    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
+        '';
   };
 })

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