From d7352cd1df518fada1d3b2fa7e79b5a3b9557ce1 Mon Sep 17 00:00:00 2001
From: avivkeller <me@aviv.sh>
Date: Thu, 28 May 2026 15:31:18 -0400
Subject: [PATCH 1/5] chore(generation): use `versions.json`

---
 .github/workflows/sync.yml                    | 77 -------------------
 .gitignore                                    |  4 +-
 .prettierignore                               |  5 +-
 HEAD_COMMIT                                   |  1 -
 README.md                                     | 53 +++++++------
 eslint.config.mjs                             |  2 +-
 package-lock.json                             |  1 -
 package.json                                  |  9 +--
 pages/index.md                                |  3 +
 pages/site.json                               |  3 +
 scripts/build.sh                              |  6 --
 scripts/clone.sh                              | 10 ---
 .../html/doc-kit.config.mjs                   | 26 +++----
 scripts/html/index.mjs                        | 36 +++++++++
 scripts/markdown.mjs                          | 37 ---------
 scripts/markdown/index.mjs                    | 52 +++++++++++++
 scripts/prepare/index.mjs                     | 42 ++++++++++
 scripts/vercel/build.sh                       |  4 +
 scripts/{ => vercel}/prepare.sh               |  1 -
 tsconfig.json                                 |  6 +-
 vercel.json                                   |  4 +-
 21 files changed, 198 insertions(+), 184 deletions(-)
 delete mode 100644 .github/workflows/sync.yml
 delete mode 100644 HEAD_COMMIT
 create mode 100644 pages/index.md
 create mode 100644 pages/site.json
 delete mode 100755 scripts/build.sh
 delete mode 100755 scripts/clone.sh
 rename doc-kit.config.mjs => scripts/html/doc-kit.config.mjs (60%)
 create mode 100644 scripts/html/index.mjs
 delete mode 100644 scripts/markdown.mjs
 create mode 100644 scripts/markdown/index.mjs
 create mode 100644 scripts/prepare/index.mjs
 create mode 100755 scripts/vercel/build.sh
 rename scripts/{ => vercel}/prepare.sh (67%)

diff --git a/.github/workflows/sync.yml b/.github/workflows/sync.yml
deleted file mode 100644
index 40ff5da6..00000000
--- a/.github/workflows/sync.yml
+++ /dev/null
@@ -1,77 +0,0 @@
-name: Sync Webpack
-
-on:
-  schedule:
-    # Run every 24 hours at 04:00 UTC
-    - cron: '0 4 * * *'
-  workflow_dispatch:
-
-permissions:
-  contents: write
-  pull-requests: write
-
-jobs:
-  sync:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-
-      - name: Get latest webpack commit
-        id: latest
-        run: |
-          LATEST=$(git ls-remote https://github.com/webpack/webpack.git refs/heads/main | cut -f1)
-          CURRENT=$(cat HEAD_COMMIT)
-          echo "latest=$LATEST" >> "$GITHUB_OUTPUT"
-          echo "current=$CURRENT" >> "$GITHUB_OUTPUT"
-          echo "Latest webpack commit: $LATEST"
-          echo "Current pinned commit: $CURRENT"
-
-      - name: Check for changes
-        id: check
-        run: |
-          if [ "${{ steps.latest.outputs.latest }}" = "${{ steps.latest.outputs.current }}" ]; then
-            echo "changed=false" >> "$GITHUB_OUTPUT"
-            echo "No changes detected, skipping sync."
-          else
-            echo "changed=true" >> "$GITHUB_OUTPUT"
-            echo "New webpack commit detected, syncing."
-          fi
-
-      - name: Setup Node.js
-        if: steps.check.outputs.changed == 'true'
-        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
-        with:
-          node-version: lts/*
-          cache: 'npm'
-
-      - name: Install dependencies
-        if: steps.check.outputs.changed == 'true'
-        run: npm ci
-
-      - name: Update HEAD_COMMIT
-        if: steps.check.outputs.changed == 'true'
-        run: echo "${{ steps.latest.outputs.latest }}" > HEAD_COMMIT
-
-      - name: Clone webpack
-        if: steps.check.outputs.changed == 'true'
-        run: npm run clone-webpack
-
-      - name: Regenerate docs
-        if: steps.check.outputs.changed == 'true'
-        run: npm run generate-docs
-
-      - name: Create pull request
-        if: steps.check.outputs.changed == 'true'
-        uses: gr2m/create-or-update-pull-request-action@b65137ca591da0b9f43bad7b24df13050ea45d1b # v1.10.1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          commit-message: 'chore: sync webpack docs to ${{ steps.latest.outputs.latest }}'
-          title: 'chore: sync webpack docs to ${{ steps.latest.outputs.latest }}'
-          body: |
-            Automated update of webpack docs.
-
-            - Latest webpack commit: ${{ steps.latest.outputs.latest }}
-            - Previous commit: ${{ steps.latest.outputs.current }}
-          branch: 'chore/sync-webpack'
diff --git a/.gitignore b/.gitignore
index c9e74aef..cf61f01c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,5 @@
 node_modules
 out
 *.generated.*
-/webpack
-/pages
\ No newline at end of file
+/.cache
+/pages/api
diff --git a/.prettierignore b/.prettierignore
index ed492156..342d8aad 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -1,7 +1,6 @@
 node_modules
 out
 *.generated.*
-/webpack
-pages
-.husky
+/.cache
+/pages/api
 versions.json
\ No newline at end of file
diff --git a/HEAD_COMMIT b/HEAD_COMMIT
deleted file mode 100644
index acd86cba..00000000
--- a/HEAD_COMMIT
+++ /dev/null
@@ -1 +0,0 @@
-0b60f1cba10640d886510999c1bfbca5f4ba7ab6
\ No newline at end of file
diff --git a/README.md b/README.md
index 1a3a1122..e3c24dc2 100644
--- a/README.md
+++ b/README.md
@@ -9,46 +9,55 @@ Automated TypeScript API documentation generator for [webpack](https://github.co
 3. **@node-core/doc-kit** converts Markdown to HTML
 4. GitHub Actions deploys the result to GitHub Pages
 
-### Webpack Version Tracking
+### Webpack Versions
 
-The `HEAD_COMMIT` file pins the exact webpack/webpack commit used for doc generation. A scheduled GitHub Action runs every 24 hours to:
+Generation expects a `versions.json` file at the project root with the webpack release tags to generate, for example:
 
-1. Fetch the latest webpack `main` branch HEAD
-2. Update `HEAD_COMMIT`
-3. Regenerate documentation
-4. Push the changes to this repository
+```json
+["v5.1.0"]
+```
 
-This ensures documentation stays in sync with upstream webpack without manual intervention.
+Each tag is fetched from the webpack npm package and generated into `pages/api/v[Major].x`. Creating or updating `versions.json` is handled outside this project.
 
 ## Project Structure
 
 ```
-├── generate-md.mjs          # TypeDoc entry point
+├── scripts/
+│   ├── prepare/              # Fetches every webpack release listed in versions.json
+│   ├── markdown/             # TypeDoc → Markdown for a single webpack source path
+│   ├── html/                 # doc-kit HTML generation
+│   └── vercel/               # Vercel install/build entry points
 ├── plugins/
-│   ├── processor.mjs         # Namespace merging + type-map generation
+│   ├── processor/            # Namespace merging + type-map generation
 │   └── theme/                # Custom doc-kit theme
-├── HEAD_COMMIT               # Pinned webpack commit SHA
+├── versions.json             # Webpack release tags to generate
 ├── .github/workflows/
-│   ├── ci.yml                # Lint + doc generation check
-│   ├── deploy.yml            # Build HTML + deploy to GitHub Pages
-│   └── sync.yml              # Daily webpack sync
+│   └── ci.yml                # Lint + format check
 └── package.json
 ```
 
+The pipeline is split into three stages: `prepare` fetches each webpack tag into `.cache/webpack/<version>/`, `markdown` is invoked once per source directory to emit Markdown under `pages/api/v<major>.x`, and `html` runs doc-kit over the result.
+
 ## Scripts
 
-| Script                  | Description                          |
-| ----------------------- | ------------------------------------ |
-| `npm run clone-webpack` | Clone webpack repo at pinned commit  |
-| `npm run generate-docs` | Generate Markdown from webpack types |
-| `npm run build-html`    | Convert Markdown to HTML             |
-| `npm run build`         | Generate docs + build HTML           |
-| `npm run lint`          | Run ESLint                           |
-| `npm run format:check`  | Check Prettier formatting            |
+| Script                 | Description                                                       |
+| ---------------------- | ----------------------------------------------------------------- |
+| `npm run prep`         | Fetch every webpack tag in `versions.json` into `.cache/webpack/` |
+| `npm run build:md`     | Generate Markdown for every prepared webpack source               |
+| `npm run build:html`   | Convert Markdown to HTML                                          |
+| `npm run build`        | Full pipeline: prepare → Markdown → HTML                          |
+| `npm run lint`         | Run ESLint                                                        |
+| `npm run format:check` | Check Prettier formatting                                         |
+
+To generate Markdown for a single webpack source, invoke the processor directly:
+
+```sh
+node scripts/markdown/index.mjs .cache/webpack/v5.107.1
+```
 
 ## Contributing
 
-When making changes to documentation generation (plugins, `generate-md.mjs`, `tsconfig.json`), ensure the docs can still be generated successfully. CI will verify this on every pull request.
+When making changes to documentation generation (plugins, `scripts/markdown/index.mjs`, `tsconfig.json`), ensure the docs can still be generated successfully. CI will verify this on every pull request.
 
 ## License
 
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 29b41289..a7118f8c 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -11,6 +11,6 @@ export default [
     },
   },
   {
-    ignores: ['node_modules/', 'out/', 'webpack/'],
+    ignores: ['node_modules/', 'out/', '.cache/', 'webpack/', 'pages/'],
   },
 ];
diff --git a/package-lock.json b/package-lock.json
index 3e6cc8ef..3d6f1dec 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -6,7 +6,6 @@
     "": {
       "dependencies": {
         "@node-core/doc-kit": "^1.3.6",
-        "semver": "^7.8.1",
         "typedoc": "^0.28.19",
         "typedoc-plugin-markdown": "^4.11.0",
         "webpack": "^5.107.1"
diff --git a/package.json b/package.json
index 6b698975..89798efb 100644
--- a/package.json
+++ b/package.json
@@ -1,9 +1,9 @@
 {
   "scripts": {
-    "clone-webpack": "bash scripts/clone.sh",
-    "generate-docs": "node scripts/markdown.mjs",
-    "build-html": "doc-kit generate -t web --config-file ./doc-kit.config.mjs",
-    "build": "npm run generate-docs && npm run build-html",
+    "prep": "node scripts/prepare/index.mjs",
+    "build:md": "node scripts/markdown/index.mjs",
+    "build:html": "node scripts/html/index.mjs",
+    "build": "npm run prep && npm run build:md && npm run build:html",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "format": "prettier --write .",
@@ -12,7 +12,6 @@
   },
   "dependencies": {
     "@node-core/doc-kit": "^1.3.6",
-    "semver": "^7.8.1",
     "typedoc": "^0.28.19",
     "typedoc-plugin-markdown": "^4.11.0",
     "webpack": "^5.107.1"
diff --git a/pages/index.md b/pages/index.md
new file mode 100644
index 00000000..e4d427d2
--- /dev/null
+++ b/pages/index.md
@@ -0,0 +1,3 @@
+---
+layout: home
+---
diff --git a/pages/site.json b/pages/site.json
new file mode 100644
index 00000000..0f6cec2b
--- /dev/null
+++ b/pages/site.json
@@ -0,0 +1,3 @@
+{
+  "sidebar": []
+}
diff --git a/scripts/build.sh b/scripts/build.sh
deleted file mode 100755
index 78b7d59b..00000000
--- a/scripts/build.sh
+++ /dev/null
@@ -1,6 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-mkdir -p out
-npm run generate-docs
-npm run build-html
diff --git a/scripts/clone.sh b/scripts/clone.sh
deleted file mode 100755
index 706aed68..00000000
--- a/scripts/clone.sh
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-WEBPACK_DIR="webpack"
-WEBPACK_REPO="https://github.com/webpack/webpack.git"
-REF="$(cat HEAD_COMMIT)"
-
-rm -rf "$WEBPACK_DIR"
-git clone "$WEBPACK_REPO" "$WEBPACK_DIR"
-git -C "$WEBPACK_DIR" checkout --detach "$REF"
diff --git a/doc-kit.config.mjs b/scripts/html/doc-kit.config.mjs
similarity index 60%
rename from doc-kit.config.mjs
rename to scripts/html/doc-kit.config.mjs
index 1c6e09ae..aa846a48 100644
--- a/doc-kit.config.mjs
+++ b/scripts/html/doc-kit.config.mjs
@@ -1,10 +1,13 @@
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { major } from 'semver';
-import webpack from './webpack/package.json' with { type: 'json' };
 
-const ROOT = dirname(fileURLToPath(import.meta.url));
-const DOCS_DIR = `pages/v${major(webpack.version)}.x`;
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+const VERSION = process.env.VERSION;
+const inputDir = join(
+  ROOT,
+  VERSION ? `./pages/api/${VERSION.split('.')[0]}.x` : './pages'
+);
 
 /**
  * Configuration for @node-core/doc-kit when generating webpack API docs.
@@ -13,21 +16,18 @@ const DOCS_DIR = `pages/v${major(webpack.version)}.x`;
  */
 export default {
   global: {
-    // Point GitHub links to the webpack repository instead of nodejs/node
     repository: 'webpack/webpack',
-
-    // Input & Output
-    input: [`./${DOCS_DIR}/**/*.md`],
-    output: 'out',
-
-    // Base URL,
+    version: VERSION,
+    input: [`${inputDir}/**/*.md`],
+    ignore: VERSION ? [] : ['./pages/api/**/*.md'],
+    output: VERSION ? `./out/api/${VERSION.split('.')[0]}.x` : './out',
     baseURL: process.env.VERCEL_URL
       ? `https://${process.env.VERCEL_URL}`
       : 'http://localhost:3000',
   },
   threads: 1,
   metadata: {
-    typeMap: `./${DOCS_DIR}/type-map.json`,
+    typeMap: VERSION ? join(inputDir, 'type-map.json') : undefined,
   },
   'jsx-ast': {
     generateIndexPage: false,
@@ -39,7 +39,7 @@ export default {
     remoteConfigUrl: null,
     imports: {
       '#theme/Sidebar': join(ROOT, 'components/SideBar.jsx'),
-      '#theme/site': join(ROOT, DOCS_DIR, 'site.json'),
+      '#theme/site': join(inputDir, 'site.json'),
       '#theme/Layout': join(ROOT, 'components/Layout.jsx'),
     },
   },
diff --git a/scripts/html/index.mjs b/scripts/html/index.mjs
new file mode 100644
index 00000000..a7cdaa37
--- /dev/null
+++ b/scripts/html/index.mjs
@@ -0,0 +1,36 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+const runDocKit = version =>
+  execFileAsync(
+    'npx',
+    [
+      '-p',
+      '@node-core/doc-kit',
+      'doc-kit',
+      'generate',
+      '-t',
+      'web',
+      '--config-file',
+      './scripts/html/doc-kit.config.mjs',
+    ],
+    {
+      env: {
+        ...process.env,
+        VERSION: version,
+      },
+    }
+  );
+
+// For each version in versions.json, run doc-kit to generate the API docs
+// Plus, once more without a version to generate the latest API docs
+
+const versions = JSON.parse(await readFile('./versions.json'));
+
+for (const version of versions) {
+  await runDocKit(version);
+}
+await runDocKit();
diff --git a/scripts/markdown.mjs b/scripts/markdown.mjs
deleted file mode 100644
index 6a094891..00000000
--- a/scripts/markdown.mjs
+++ /dev/null
@@ -1,37 +0,0 @@
-import { Application } from 'typedoc';
-import webpack from '../webpack/package.json' with { type: 'json' };
-import { major } from 'semver';
-
-const app = await Application.bootstrapWithPlugins({
-  entryPoints: ['./webpack/types.d.ts'],
-  out: `pages/v${major(webpack.version)}.x`,
-
-  // Plugins
-  plugin: [
-    'typedoc-plugin-markdown',
-    './plugins/processor/index.mjs',
-    './plugins/theme/index.mjs',
-  ],
-  theme: 'doc-kit',
-  router: 'doc-kit',
-  publicPath: '/',
-
-  // Formatting
-  hideGroupHeadings: true,
-  hideBreadcrumbs: true,
-  hidePageHeader: true,
-  readme: 'none',
-  disableSources: true,
-  propertiesFormat: 'table',
-  membersWithOwnFile: ['Class'],
-
-  modulesFileName: 'index',
-  entryFileName: 'index',
-  tsconfig: 'tsconfig.json',
-});
-
-const project = await app.convert();
-
-if (project) {
-  await app.generateOutputs(project);
-}
diff --git a/scripts/markdown/index.mjs b/scripts/markdown/index.mjs
new file mode 100644
index 00000000..858bdb83
--- /dev/null
+++ b/scripts/markdown/index.mjs
@@ -0,0 +1,52 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Application } from 'typedoc';
+import { major } from 'semver';
+
+const CACHE_DIR = join('.', '.cache', 'webpack');
+
+const generate = async packageDir => {
+  const { version } = JSON.parse(
+    await readFile(join(packageDir, 'package.json'), 'utf8')
+  );
+
+  const app = await Application.bootstrapWithPlugins({
+    entryPoints: [join(packageDir, 'types.d.ts')],
+    out: join('pages', 'api', `v${major(version)}.x`),
+
+    plugin: [
+      'typedoc-plugin-markdown',
+      './plugins/processor/index.mjs',
+      './plugins/theme/index.mjs',
+    ],
+    theme: 'doc-kit',
+    router: 'doc-kit',
+
+    hideGroupHeadings: true,
+    hideBreadcrumbs: true,
+    hidePageHeader: true,
+    readme: 'none',
+    disableSources: true,
+    propertiesFormat: 'table',
+    membersWithOwnFile: ['Class'],
+
+    modulesFileName: 'index',
+    entryFileName: 'index',
+    tsconfig: 'tsconfig.json',
+  });
+
+  const project = await app.convert();
+  await app.generateOutputs(project);
+};
+
+const [packageDir] = process.argv.slice(2);
+
+const sources = packageDir
+  ? [packageDir]
+  : (await readdir(CACHE_DIR, { withFileTypes: true }))
+      .filter(entry => entry.isDirectory())
+      .map(entry => join(CACHE_DIR, entry.name));
+
+for (const source of sources) {
+  await generate(source);
+}
diff --git a/scripts/prepare/index.mjs b/scripts/prepare/index.mjs
new file mode 100644
index 00000000..730d20b8
--- /dev/null
+++ b/scripts/prepare/index.mjs
@@ -0,0 +1,42 @@
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, rmSync, unlinkSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const CACHE_DIR = join('.', '.cache', 'webpack');
+
+const execOptions = {
+  stdio: ['ignore', 'pipe', 'inherit'],
+  encoding: 'utf8',
+};
+
+const fetchWebpack = version => {
+  console.log(`Fetching webpack ${version}`);
+
+  const [{ filename }] = JSON.parse(
+    execFileSync(
+      'npm',
+      ['pack', `webpack@${version}`, '--json', '--pack-destination', CACHE_DIR],
+      execOptions
+    )
+  );
+  const archive = join(CACHE_DIR, filename);
+  const destination = join(CACHE_DIR, version);
+
+  rmSync(destination, { recursive: true, force: true });
+  mkdirSync(destination, { recursive: true });
+  execFileSync(
+    'tar',
+    ['-xzf', archive, '-C', destination, '--strip-components=1'],
+    execOptions
+  );
+  unlinkSync(archive);
+};
+
+rmSync(CACHE_DIR, { recursive: true, force: true });
+mkdirSync(CACHE_DIR, { recursive: true });
+
+const versions = JSON.parse(await readFile('./versions.json'));
+for (const version of versions) {
+  fetchWebpack(version);
+}
diff --git a/scripts/vercel/build.sh b/scripts/vercel/build.sh
new file mode 100755
index 00000000..584604d7
--- /dev/null
+++ b/scripts/vercel/build.sh
@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+npm run build
diff --git a/scripts/prepare.sh b/scripts/vercel/prepare.sh
similarity index 67%
rename from scripts/prepare.sh
rename to scripts/vercel/prepare.sh
index ce618e76..3822d1fc 100755
--- a/scripts/prepare.sh
+++ b/scripts/vercel/prepare.sh
@@ -2,4 +2,3 @@
 set -euo pipefail
 
 npm ci
-bash scripts/clone.sh
diff --git a/tsconfig.json b/tsconfig.json
index a63a91a3..68e3f0ac 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,8 +1,8 @@
 {
   "include": [
-    "./webpack/lib/**/*",
-    "./webpack/declarations/**/*",
-    "./webpack/types.d.ts"
+    "./.cache/webpack/*/lib/**/*",
+    "./.cache/webpack/*/declarations/**/*",
+    "./.cache/webpack/*/types.d.ts"
   ],
   "exclude": ["node_modules"],
   "compilerOptions": {
diff --git a/vercel.json b/vercel.json
index 3c2ce58c..da0ce792 100644
--- a/vercel.json
+++ b/vercel.json
@@ -3,6 +3,6 @@
   "outputDirectory": "out",
   "cleanUrls": true,
   "trailingSlash": false,
-  "installCommand": "bash scripts/prepare.sh",
-  "buildCommand": "bash scripts/build.sh"
+  "installCommand": "bash scripts/vercel/prepare.sh",
+  "buildCommand": "bash scripts/vercel/build.sh"
 }

From 5c2352a360bc80c3c534d4ff6e57bfb091dd0317 Mon Sep 17 00:00:00 2001
From: avivkeller <me@aviv.sh>
Date: Thu, 28 May 2026 15:31:55 -0400
Subject: [PATCH 2/5] fixup!

---
 eslint.config.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/eslint.config.mjs b/eslint.config.mjs
index a7118f8c..c79a995e 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -11,6 +11,6 @@ export default [
     },
   },
   {
-    ignores: ['node_modules/', 'out/', '.cache/', 'webpack/', 'pages/'],
+    ignores: ['node_modules/', 'out/', '.cache/', 'webpack/', 'pages/api'],
   },
 ];

From 86790d7d6d45140e298db4840fffede631ce762c Mon Sep 17 00:00:00 2001
From: avivkeller <me@aviv.sh>
Date: Thu, 28 May 2026 15:43:36 -0400
Subject: [PATCH 3/5] fixup!

---
 plugins/processor/index.mjs | 2 +-
 plugins/processor/site.mjs  | 5 +++--
 scripts/markdown/index.mjs  | 1 +
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/plugins/processor/index.mjs b/plugins/processor/index.mjs
index eacf6b11..12f07d05 100644
--- a/plugins/processor/index.mjs
+++ b/plugins/processor/index.mjs
@@ -54,7 +54,7 @@ export function load(app) {
       join(app.options.getValue('out'), 'site.json'),
       JSON.stringify(
         {
-          sidebar: sidebar(app.renderer.router),
+          sidebar: sidebar(app.renderer.router, app.options.getValue('base')),
         },
         null,
         2
diff --git a/plugins/processor/site.mjs b/plugins/processor/site.mjs
index b4def82b..890dcc91 100644
--- a/plugins/processor/site.mjs
+++ b/plugins/processor/site.mjs
@@ -10,9 +10,10 @@ const getFirstAtxHeading = text => text.match(/^#\s+(.+)$/m)?.[1]?.trim();
 
 const getFirstPathSegment = url => url.replace(/^\//, '').split('/')[0];
 
-const toSidebarLink = url => {
+const toSidebarLink = (url, basePath) => {
   const path = url.replace(/\.md$/, '').replace(/\/index$/, '');
-  return path ? `/${path}` : '/';
+  const prefix = basePath ? `/${basePath.replace(/^\/|\/$/g, '')}` : '';
+  return path ? `${prefix}/${path}` : prefix || '/';
 };
 
 const defaultLabelFor = (target, url) => {
diff --git a/scripts/markdown/index.mjs b/scripts/markdown/index.mjs
index 858bdb83..3509d488 100644
--- a/scripts/markdown/index.mjs
+++ b/scripts/markdown/index.mjs
@@ -13,6 +13,7 @@ const generate = async packageDir => {
   const app = await Application.bootstrapWithPlugins({
     entryPoints: [join(packageDir, 'types.d.ts')],
     out: join('pages', 'api', `v${major(version)}.x`),
+    base: `api/v${major(version)}.x`,
 
     plugin: [
       'typedoc-plugin-markdown',

From b2d3ee2838a75d1d5f0c722ee1615f7974a58180 Mon Sep 17 00:00:00 2001
From: avivkeller <me@aviv.sh>
Date: Thu, 28 May 2026 15:46:03 -0400
Subject: [PATCH 4/5] fixup!

---
 plugins/processor/index.mjs | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/plugins/processor/index.mjs b/plugins/processor/index.mjs
index 12f07d05..a55c204f 100644
--- a/plugins/processor/index.mjs
+++ b/plugins/processor/index.mjs
@@ -11,9 +11,8 @@ import { createTypeMap } from './typeMap.mjs';
  * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
  */
 export function load(app) {
-  // Keep router ownership in the processor plugin because routing depends on
-  // source metadata and the synthetic type pages created during conversion.
   app.renderer.defineRouter('doc-kit', DocKitRouter);
+  app.options.addDeclaration({ name: 'base' });
 
   app.converter.on(Converter.EVENT_RESOLVE_BEGIN, context => {
     // doc-kit has property metadata, not TypeDoc accessor metadata.

From 8c73cb09cf91b12476dbe1bec04a94d31dd5cfaf Mon Sep 17 00:00:00 2001
From: avivkeller <me@aviv.sh>
Date: Thu, 28 May 2026 15:49:07 -0400
Subject: [PATCH 5/5] fixup!

---
 plugins/processor/site.mjs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/plugins/processor/site.mjs b/plugins/processor/site.mjs
index 890dcc91..62ddc107 100644
--- a/plugins/processor/site.mjs
+++ b/plugins/processor/site.mjs
@@ -30,7 +30,7 @@ const isSidebarTarget = (router, target) => {
   return url.endsWith('.md') && !url.includes('#');
 };
 
-export const sidebar = router => {
+export const sidebar = (router, basePath) => {
   const categories = new Map();
   const seen = new Set();
 
@@ -59,7 +59,7 @@ export const sidebar = router => {
     };
 
     group.items.push({
-      link: toSidebarLink(url),
+      link: toSidebarLink(url, basePath),
       label,
     });