use friendly "semi-stable" urls for key versions (#256)

Currently all of the versioned docs have the explicit version in the
url. This has the virtue of being
[cool](https://www.w3.org/Provider/Style/URI) but has some awkwardness
in practice. For example if one links to
https://www.pantsbuild.org/2.18/docs/using-pants/using-pants-in-ci from
another webpage it will eventualy end up with the 'no longer maintained'
banner. It isn't super fun to update every internal/wiki link every 6
weeks for a release.

This change introduces some "semi-stable" urls for key versions:
 * `prerelease`: The latest prerelease
 * `dev`: aka `main` aka "trunk"
 * `stable`: The most recent stable release

Redirects ensure that the versioned urls also work.

As an example, right now:

`/stable/docs/using-pants/using-pants-in-ci` is the doc for `2.21` and
`/2.21//docs/using-pants/using-pants-in-ci` redirects to there. After
the next release, `/stable/docs/using-pants/using-pants-in-ci` will be
for `2.22` and `/2.21/docs/using-pants/using-pants-in-ci` will keep
pointing to the `2.21` content.

I think this is reasonable compromise of easy of use with permanence.

FWIW the Offical Docusaurus position seems to be to prefer server side
redirects facebook/docusaurus#9049 but as far
as I can tell that isn't an option for GitHub Pages.

ref #221

.github/workflows/deploy.yml

@@ -52,8 +52,8 @@ jobs:
       - run: yarn install --frozen-lockfile
       - run: npm run build
         env:
+          NODE_ENV: "production"
           NODE_OPTIONS: --max-old-space-size=12288
-
       - name: Setup Pages
         uses: actions/configure-pages@v3
       - name: Upload artifact

README.md

@@ -62,7 +62,7 @@ PANTSBUILD_ORG_INCLUDE_VERSIONS=$version1,$version2 npm start
 To build the site, run:
 
 ```bash
-NODE_OPTIONS="--max-old-space-size=12288" npm run build
+NODE_ENV=production NODE_OPTIONS="--max-old-space-size=12288" npm run build
 ```
 
 (Note: Node needs more than the default amount of RAM because this site is beefy)

docusaurus.config.js

@@ -1,5 +1,5 @@
 import versions from "./versions.json";
-import redirects from "./old_site_redirects.js";
+import old_site_redirects from "./old_site_redirects.js";
 import captionedCode from "./src/remark/captioned-code.js";
 import tabBlocks from "docusaurus-remark-plugin-tab-blocks";
 import fs from "fs";
@@ -29,6 +29,8 @@ const onlyIncludeVersions = isDev
     : ["current"]
   : undefined;
 
+// In Docusaurus terms, "current" == main == trunk == dev.  It is *newer* than
+// the newest in versions.json
 function getCurrentVersion() {
   const lastReleasedVersion = versions[0];
   const version = parseInt(lastReleasedVersion.replace("2.", ""), 10);
@@ -71,6 +73,7 @@ const getVersionDetails = () => {
   const versionDetails = [];
 
   let seenStableVersions = 0;
+  let newestPreReleaseVersion = null;
 
   // Construct the configuration for each version. NB. iterating from newest to oldest is important,
   // to be able to label too-old stable versions as unsupported.
@@ -81,34 +84,42 @@ const getVersionDetails = () => {
     const isMaintained = seenStableVersions < numberOfSupportedStableVersions;
     const isPrerelease = isPrereleaseVersion(fullVersion);
     const isCurrent = isCurrentVersion(shortVersion);
+    if (!isCurrent && isPrerelease && newestPreReleaseVersion === null) {
+      newestPreReleaseVersion = shortVersion;
+    }
 
     // compute the appropriate configuration this version
     let config;
     if (isCurrent) {
       // current version => dev
       config = {
         label: `${shortVersion} (dev)`,
+        path: "dev",
       };
     } else if (isPrerelease) {
       // prerelease => prerelease
       config = {
         label: `${shortVersion} (prerelease)`,
         banner: "unreleased",
         noIndex: false,
+        path:
+          shortVersion == newestPreReleaseVersion ? "prerelease" : shortVersion,
       };
     } else if (isMaintained) {
       // a new-enough stable version => so still supported
       config = {
         label: shortVersion,
         banner: "none",
         noIndex: false,
+        path: seenStableVersions == 0 ? "stable" : shortVersion,
       };
     } else {
       // stable, but too old => deprecated
       config = {
         label: `${shortVersion} (deprecated)`,
         banner: "unmaintained",
         noIndex: true,
+        path: shortVersion,
       };
     }
 
@@ -118,22 +129,22 @@ const getVersionDetails = () => {
       isMaintained,
       isPrerelease,
       isCurrent,
-      config: {
-        ...config,
-        path: shortVersion,
-      },
+      config,
     });
 
     if (!isPrerelease) {
       seenStableVersions += 1;
     }
   }
-
   return versionDetails;
 };
 
 const versionDetails = getVersionDetails();
 
+const mostRecentPreReleaseVersion = versionDetails.find(
+  ({ isMaintained }) => !isMaintained
+);
+
 const mostRecentStableVersion = versionDetails.find(
   ({ isPrerelease }) => !isPrerelease
 );
@@ -434,7 +445,27 @@ const config = {
     [
       "@docusaurus/plugin-client-redirects",
       {
-        redirects,
+        redirects: old_site_redirects,
+        createRedirects(existingPath) {
+          if (existingPath.startsWith("/dev/")) {
+            return [existingPath.replace("/dev/", `/${currentVersion}/`)];
+          } else if (existingPath.startsWith("/prerelease/")) {
+            return [
+              existingPath.replace(
+                "/prerelease/",
+                `/${mostRecentPreReleaseVersion.shortVersion}/`
+              ),
+            ];
+          } else if (existingPath.startsWith("/stable/")) {
+            return [
+              existingPath.replace(
+                "/stable/",
+                `/${mostRecentStableVersion.shortVersion}/`
+              ),
+            ];
+          }
+          return undefined;
+        },
       },
     ],
   ],