From 525bc480a76b4561d65c53cecf3e6f94c19fc175 Mon Sep 17 00:00:00 2001 From: Chris Burroughs Date: Tue, 27 Aug 2024 16:23:17 -0400 Subject: [PATCH 1/2] use friendly "semi-stable" urls for key versions 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 https://github.com/facebook/docusaurus/issues/9049 but as far as I can tell that isn't an option for GitHub Pages. ref #221 --- .github/workflows/deploy.yml | 2 +- README.md | 2 +- docusaurus.config.js | 45 ++++++++++++++++++++++++++++++------ 3 files changed, 40 insertions(+), 9 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 5e108146..3ef094f9 100644 --- a/.github/workflows/deploy.yml +++ b/.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 diff --git a/README.md b/README.md index f79fa66c..740de2a4 100644 --- a/README.md +++ b/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) diff --git a/docusaurus.config.js b/docusaurus.config.js index 2dda7af7..3abf1f8e 100644 --- a/docusaurus.config.js +++ b/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,6 +84,9 @@ 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; @@ -88,6 +94,7 @@ const getVersionDetails = () => { // current version => dev config = { label: `${shortVersion} (dev)`, + path: "dev", }; } else if (isPrerelease) { // prerelease => prerelease @@ -95,6 +102,8 @@ const getVersionDetails = () => { label: `${shortVersion} (prerelease)`, banner: "unreleased", noIndex: false, + path: + shortVersion == newestPreReleaseVersion ? "prerelease" : shortVersion, }; } else if (isMaintained) { // a new-enough stable version => so still supported @@ -102,6 +111,7 @@ const getVersionDetails = () => { label: shortVersion, banner: "none", noIndex: false, + path: seenStableVersions == 0 ? "stable" : shortVersion, }; } else { // stable, but too old => deprecated @@ -109,6 +119,7 @@ const getVersionDetails = () => { 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.includes("/dev/")) { + return [existingPath.replace("/dev/", `/${currentVersion}/`)]; + } else if (existingPath.includes("/prerelease/")) { + return [ + existingPath.replace( + "/prerelease/", + `/${mostRecentPreReleaseVersion.shortVersion}/` + ), + ]; + } else if (existingPath.includes("/stable/")) { + return [ + existingPath.replace( + "/stable/", + `/${mostRecentStableVersion.shortVersion}/` + ), + ]; + } + return undefined; + }, }, ], ], From e4fb256a787f8fca4c116d66d5d9c2466144b3fe Mon Sep 17 00:00:00 2001 From: Chris Burroughs Date: Wed, 28 Aug 2024 10:16:33 -0400 Subject: [PATCH 2/2] switch ot startsWith for redirect check --- docusaurus.config.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 3abf1f8e..0b90d975 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -447,16 +447,16 @@ const config = { { redirects: old_site_redirects, createRedirects(existingPath) { - if (existingPath.includes("/dev/")) { + if (existingPath.startsWith("/dev/")) { return [existingPath.replace("/dev/", `/${currentVersion}/`)]; - } else if (existingPath.includes("/prerelease/")) { + } else if (existingPath.startsWith("/prerelease/")) { return [ existingPath.replace( "/prerelease/", `/${mostRecentPreReleaseVersion.shortVersion}/` ), ]; - } else if (existingPath.includes("/stable/")) { + } else if (existingPath.startsWith("/stable/")) { return [ existingPath.replace( "/stable/",