feat: automate docs version snapshot during release

.github/workflows/release.yml

@@ -58,13 +58,14 @@ jobs:
                 path: |
                     **/node_modules
                     ~/.bun/install/cache
-                key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lockb') }}
+                key: ${{ runner.os }}-bun-${{ hashFiles('bun.lockb', 'docs/bun.lock') }}
                 restore-keys: |
                     ${{ runner.os }}-bun-
 
             - name: Install dependencies
               run: |
                   bun install
+                  cd docs && bun install
 
             # Validate version before release (tag protection)
             - name: Validate release

docs/docusaurus.config.js

@@ -5,6 +5,15 @@ const {themes} = require('prism-react-renderer');
 const lightCodeTheme = themes.github;
 const darkCodeTheme = themes.dracula;
 
+let docsVersions = [];
+try {
+  docsVersions = require('./versions.json');
+} catch {
+  docsVersions = [];
+}
+
+const latestStableVersion = docsVersions[0];
+
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: 'QuickAdd',
@@ -37,17 +46,21 @@ const config = {
           sidebarPath: require.resolve('./sidebars.js'),
           editUrl:
             'https://github.com/chhoumann/quickadd/tree/master/docs/',
-          lastVersion: '2.9.4',
+          ...(latestStableVersion ? {lastVersion: latestStableVersion} : {}),
           versions: {
             current: {
               label: 'Next 🚧',
               path: 'next',
               banner: 'unreleased',
             },
-            '2.9.4': {
-              label: '2.9.4',
-              path: '',
-            },
+            ...(latestStableVersion
+              ? {
+                  [latestStableVersion]: {
+                    label: latestStableVersion,
+                    path: '',
+                  },
+                }
+              : {}),
           },
         },
         blog: {

package.json

@@ -86,14 +86,18 @@
           "npmPublish": false
         }
       ],
+      "./scripts/release/docs-versioning-plugin.cjs",
       [
         "@semantic-release/git",
         {
           "assets": [
             "package.json",
             "package-lock.json",
             "manifest.json",
-            "versions.json"
+            "versions.json",
+            "docs/versions.json",
+            "docs/versioned_docs/**/*",
+            "docs/versioned_sidebars/*.json"
           ],
           "message": "release(version): Release ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
         }

scripts/release/docs-versioning-plugin.cjs

@@ -0,0 +1,38 @@
+const { execFileSync } = require("node:child_process");
+const path = require("node:path");
+
+const STABLE_VERSION_REGEX = /^\d+\.\d+\.\d+$/;
+const versionDocsScriptPath = path.resolve(__dirname, "version-docs.mjs");
+
+module.exports = {
+	prepare: (_, context) => {
+		const { nextRelease, logger } = context;
+		const version = nextRelease && nextRelease.version;
+
+		if (!version) {
+			logger.log("No release version found. Skipping docs versioning.");
+			return;
+		}
+
+		if (!STABLE_VERSION_REGEX.test(version)) {
+			logger.log(
+				`Skipping docs snapshot for non-stable release ${version}.`,
+			);
+			return;
+		}
+
+		logger.log(`Running docs snapshot for stable release ${version}.`);
+
+		try {
+			execFileSync(process.execPath, [versionDocsScriptPath, version], {
+				cwd: process.cwd(),
+				stdio: "inherit",
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			throw new Error(
+				`Docs versioning failed for ${version}: ${message}`,
+			);
+		}
+	},
+};

scripts/release/version-docs.mjs

@@ -0,0 +1,55 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const STABLE_VERSION_REGEX = /^\d+\.\d+\.\d+$/;
+
+function fail(message) {
+	console.error(`[docs-versioning] ${message}`);
+	process.exit(1);
+}
+
+const version = process.argv[2];
+
+if (!version) {
+	fail("Missing version argument.");
+}
+
+if (!STABLE_VERSION_REGEX.test(version)) {
+	fail(`Version "${version}" is not a stable X.Y.Z release.`);
+}
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(scriptDir, "..", "..");
+const docsDir = path.join(repoRoot, "docs");
+const versionedDocsDir = path.join(
+	docsDir,
+	"versioned_docs",
+	`version-${version}`,
+);
+
+if (!existsSync(docsDir)) {
+	fail(`Docs directory not found: ${docsDir}`);
+}
+
+if (existsSync(versionedDocsDir)) {
+	console.log(
+		`[docs-versioning] Snapshot already exists for ${version}. Skipping.`,
+	);
+	process.exit(0);
+}
+
+console.log(`[docs-versioning] Creating docs snapshot for ${version}.`);
+
+try {
+	execFileSync("bun", ["run", "docusaurus", "docs:version", version], {
+		cwd: docsDir,
+		stdio: "inherit",
+	});
+} catch (error) {
+	const message = error instanceof Error ? error.message : String(error);
+	fail(`Failed to snapshot docs for ${version}: ${message}`);
+}
+
+console.log(`[docs-versioning] Snapshot completed for ${version}.`);