fix(docs): correct versioned nav links and local dev version routing (#74)

docs-site/.vitepress/config.ts

@@ -1,5 +1,5 @@
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, posix, resolve, sep } from 'node:path';
 import type { DefaultTheme, HeadConfig, TransformContext, UserConfig } from 'vitepress';
 
 const DOCS_HOSTNAME = 'https://docs.subminer.moe';
@@ -21,10 +21,16 @@ type VersionManifest = {
 
 const base = normalizeBase(process.env.SUBMINER_DOCS_BASE ?? '/');
 const outDir = process.env.SUBMINER_DOCS_OUT_DIR;
+const docsSourceDir = process.env.SUBMINER_DOCS_SOURCE_DIR ?? process.cwd();
+const localArchiveDir = resolve(
+  process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR ??
+    join(docsSourceDir, '..', '.tmp/docs-versioned-site'),
+);
 const channel = normalizeChannel(process.env.SUBMINER_DOCS_CHANNEL);
 const docsVersion = process.env.SUBMINER_DOCS_VERSION;
 const latestStable = process.env.SUBMINER_DOCS_LATEST_STABLE ?? 'v0.14.0';
 const versionManifest = parseVersionManifest(process.env.SUBMINER_DOCS_VERSION_MANIFEST);
+const versionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN ?? 'production';
 
 function normalizeBase(value: string): string {
   if (!value || value === '/') return '/';
@@ -113,7 +119,7 @@ function linkToPagePath(link: string): string | null {
 function hasPageForLink(link: string): boolean {
   const pagePath = linkToPagePath(link);
   if (!pagePath) return true;
-  return existsSync(join(process.cwd(), pagePath));
+  return existsSync(join(docsSourceDir, pagePath));
 }
 
 function filterNav(items: DefaultTheme.NavItem[]): DefaultTheme.NavItem[] {
@@ -141,17 +147,130 @@ function filterSidebar(items: DefaultTheme.SidebarItem[]): DefaultTheme.SidebarI
     .filter((item): item is DefaultTheme.SidebarItem => Boolean(item));
 }
 
+function versionSwitchLink(path: string): string {
+  if (/^[a-z]+:\/\//i.test(path)) return path;
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  if (versionLinkOrigin === 'local') return localVersionSwitchLink(normalizedPath);
+  return `${DOCS_HOSTNAME}${normalizedPath}`;
+}
+
+function localVersionSwitchLink(path: string): string {
+  if (base === '/') return path;
+
+  const basePath = base.replace(/\/$/, '');
+  const targetPath = path === '/' ? '/' : path.replace(/\/$/, '');
+  const relativePath = posix.relative(basePath, targetPath) || '.';
+
+  return path.endsWith('/') ? `${relativePath}/` : relativePath;
+}
+
+function shouldHandleLocalVersionRoute(pathname: string): boolean {
+  if (base !== '/' || channel !== 'stable-root') return false;
+  return /^\/main(?:\/|$)/.test(pathname) || /^\/v\/[^/]+(?:\/|$)/.test(pathname);
+}
+
+function contentTypeForPath(path: string): string {
+  switch (extname(path)) {
+    case '.css':
+      return 'text/css; charset=utf-8';
+    case '.gif':
+      return 'image/gif';
+    case '.ico':
+      return 'image/x-icon';
+    case '.jpg':
+    case '.jpeg':
+      return 'image/jpeg';
+    case '.js':
+    case '.mjs':
+      return 'text/javascript; charset=utf-8';
+    case '.json':
+    case '.jsonc':
+      return 'application/json; charset=utf-8';
+    case '.mp4':
+      return 'video/mp4';
+    case '.png':
+      return 'image/png';
+    case '.svg':
+      return 'image/svg+xml';
+    case '.ttf':
+      return 'font/ttf';
+    case '.webm':
+      return 'video/webm';
+    case '.woff':
+      return 'font/woff';
+    case '.woff2':
+      return 'font/woff2';
+    case '.xml':
+      return 'application/xml; charset=utf-8';
+    default:
+      return 'text/html; charset=utf-8';
+  }
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function archiveFileForPathname(pathname: string): string | null {
+  if (!shouldHandleLocalVersionRoute(pathname)) return null;
+
+  const routePath = decodeURIComponent(pathname).replace(/^\/+/, '');
+  const filePath = resolve(localArchiveDir, routePath);
+  if (filePath !== localArchiveDir && !filePath.startsWith(`${localArchiveDir}${sep}`)) {
+    return null;
+  }
+
+  const candidates = pathname.endsWith('/')
+    ? [join(filePath, 'index.html')]
+    : extname(filePath)
+      ? [filePath]
+      : [`${filePath}.html`, join(filePath, 'index.html')];
+
+  return candidates.find(isFile) ?? null;
+}
+
+function serveLocalArchiveRoute(pathname: string, response: DevServerResponse): boolean {
+  if (versionLinkOrigin !== 'local') return false;
+
+  const filePath = archiveFileForPathname(pathname);
+  if (!filePath) return false;
+
+  response.statusCode = 200;
+  response.setHeader('Content-Type', contentTypeForPath(filePath));
+  response.end(readFileSync(filePath));
+  return true;
+}
+
+type DevServerResponse = {
+  statusCode: number;
+  setHeader(name: string, value: string): void;
+  end(chunk?: string | Uint8Array): void;
+};
+
 const versionItems = [
   {
     text: `Latest stable (${versionManifest.latestStable})`,
-    link: '/',
+    link: versionSwitchLink('/'),
+    target: '_self',
+    noIcon: true,
   },
   ...versionManifest.channels
     .filter((entry) => entry.label !== 'Latest stable')
-    .map((entry) => ({ text: entry.label, link: entry.path })),
+    .map((entry) => ({
+      text: entry.label,
+      link: versionSwitchLink(entry.path),
+      target: '_self',
+      noIcon: true,
+    })),
   ...versionManifest.versions.map((entry) => ({
     text: entry.version,
-    link: entry.path,
+    link: versionSwitchLink(entry.path),
+    target: '_self',
+    noIcon: true,
   })),
 ];
 
@@ -217,6 +336,33 @@ const config: UserConfig = {
     'SubMiner: an MPV immersion-mining overlay with Yomitan and AnkiConnect integration.',
   base,
   ...(outDir ? { outDir } : {}),
+  vite: {
+    plugins: [
+      {
+        name: 'subminer-docs-local-version-redirects',
+        configureServer(server) {
+          server.middlewares.use((request, response, next) => {
+            const requestUrl = new URL(request.url ?? '/', 'http://localhost');
+            if (serveLocalArchiveRoute(requestUrl.pathname, response)) {
+              return;
+            }
+
+            if (!shouldHandleLocalVersionRoute(requestUrl.pathname)) {
+              next();
+              return;
+            }
+
+            response.statusCode = 302;
+            response.setHeader(
+              'Location',
+              `${DOCS_HOSTNAME}${requestUrl.pathname}${requestUrl.search}`,
+            );
+            response.end();
+          });
+        },
+      },
+    ],
+  },
   head: [
     ['link', { rel: 'preconnect', href: PLAUSIBLE_PROXY_HOSTNAME }],
     [
@@ -268,7 +414,7 @@ const config: UserConfig = {
   },
   transformHead: transformPageHead,
   lastUpdated: true,
-  srcExclude: ['subagents/**'],
+  srcExclude: ['subagents/**', 'README.md'],
   markdown: {
     theme: {
       light: 'catppuccin-latte',
@@ -277,8 +423,8 @@ const config: UserConfig = {
   },
   themeConfig: {
     logo: {
-      light: withDocsBase('/assets/SubMiner.png'),
-      dark: withDocsBase('/assets/SubMiner.png'),
+      light: '/assets/SubMiner.png',
+      dark: '/assets/SubMiner.png',
     },
     siteTitle: 'SubMiner Docs',
     nav: filterNav(nav),

docs-site/.vitepress/theme/components/StatusLine.vue

@@ -1,6 +1,7 @@
 <script setup>
 import { useRoute, useData } from 'vitepress';
 import { computed } from 'vue';
+import { formatStatusLineFilePath } from '../status-line';
 
 const route = useRoute();
 const { page, frontmatter } = useData();
@@ -12,8 +13,7 @@ const mode = computed(() => {
 });
 
 const filePath = computed(() => {
-  const path = route.path;
-  return path === '/' ? 'index.md' : `${path.replace(/^\//, '')}.md`;
+  return formatStatusLineFilePath(route.path);
 });
 
 const section = computed(() => {

docs-site/.vitepress/theme/status-line.test.ts

@@ -0,0 +1,16 @@
+import { expect, test } from 'bun:test';
+import { formatStatusLineFilePath } from './status-line';
+
+test('status line file path formats root home as index markdown', () => {
+  expect(formatStatusLineFilePath('/')).toBe('index.md');
+});
+
+test('status line file path formats version archive home without trailing slash', () => {
+  expect(formatStatusLineFilePath('/v/0.12.0/')).toBe('v/0.12.0.md');
+});
+
+test('status line file path keeps normal docs routes as markdown files', () => {
+  expect(formatStatusLineFilePath('/v/0.12.0/configuration')).toBe(
+    'v/0.12.0/configuration.md',
+  );
+});

docs-site/.vitepress/theme/status-line.ts

@@ -0,0 +1,4 @@
+export function formatStatusLineFilePath(routePath: string): string {
+  if (routePath === '/') return 'index.md';
+  return `${routePath.replace(/^\/|\/$/g, '')}.md`;
+}

docs-site/development.md

@@ -119,7 +119,7 @@ For production docs routing, run the versioned build:
 bun run docs:build:versioned
 ```
 
-The versioned build writes `.tmp/docs-versioned-site` with latest stable docs at `/`, development docs at `/main/`, and stable archives under `/v/<version>/`. Prerelease tags are skipped.
+The versioned build writes `.tmp/docs-versioned-site` with latest stable docs at `/`, development docs at `/main/`, and stable archives under `/v/<version>/`. Prerelease tags are skipped. Public assets from `docs-site/public/assets` are shared from root `/assets/` so large demo media is not duplicated into every version archive; generated VitePress CSS and JS assets stay under each version route. Stale `.tmp/docs-versioned-archive-cache` generations are pruned after a successful build, and intermediate `.tmp/docs-versioned-build` workspaces are removed.
 
 Focused commands:
 
@@ -162,6 +162,7 @@ bun run format:check:src
 - `make pretty` runs the maintained Prettier allowlist only (`format:src`).
 - `bun run format:check:src` checks the same scoped set without writing changes.
 - `bun run format` remains the broad repo-wide Prettier command; use it intentionally.
+
 ## Config Generation
 
 ```bash
@@ -205,17 +206,17 @@ Use Cloudflare's single `*` wildcard syntax for watch paths. `docs-site/*` cover
 
 Run `make help` for a full list of targets. Key ones:
 
-| Target                 | Description                                                      |
-| ---------------------- | ---------------------------------------------------------------- |
-| `make build`           | Build platform package for detected OS                           |
-| `make build-launcher`  | Generate Bun launcher wrapper at `dist/launcher/subminer`        |
-| `make install`         | Install platform artifacts (wrapper, theme, AppImage/app bundle) |
-| `make deps`            | Install JS dependencies (root + stats + texthooker-ui)           |
-| `make pretty`          | Run scoped Prettier formatting for maintained source/config files |
-| `make generate-config` | Generate default config from centralized registry                |
-| `make build-linux`     | Convenience wrapper for Linux packaging                          |
-| `make build-macos`     | Convenience wrapper for signed macOS packaging                   |
-| `make build-macos-unsigned` | Convenience wrapper for unsigned macOS packaging            |
+| Target                      | Description                                                       |
+| --------------------------- | ----------------------------------------------------------------- |
+| `make build`                | Build platform package for detected OS                            |
+| `make build-launcher`       | Generate Bun launcher wrapper at `dist/launcher/subminer`         |
+| `make install`              | Install platform artifacts (wrapper, theme, AppImage/app bundle)  |
+| `make deps`                 | Install JS dependencies (root + stats + texthooker-ui)            |
+| `make pretty`               | Run scoped Prettier formatting for maintained source/config files |
+| `make generate-config`      | Generate default config from centralized registry                 |
+| `make build-linux`          | Convenience wrapper for Linux packaging                           |
+| `make build-macos`          | Convenience wrapper for signed macOS packaging                    |
+| `make build-macos-unsigned` | Convenience wrapper for unsigned macOS packaging                  |
 
 ## Contributor Notes
 

docs-site/docs-sync.test.ts

@@ -8,6 +8,7 @@ const installationContents = readFileSync(new URL('./installation.md', import.me
 const mpvPluginContents = readFileSync(new URL('./mpv-plugin.md', import.meta.url), 'utf8');
 const developmentContents = readFileSync(new URL('./development.md', import.meta.url), 'utf8');
 const changelogContents = readFileSync(new URL('./changelog.md', import.meta.url), 'utf8');
+const docsPackageContents = readFileSync(new URL('./package.json', import.meta.url), 'utf8');
 const ankiIntegrationContents = readFileSync(
   new URL('./anki-integration.md', import.meta.url),
   'utf8',
@@ -57,6 +58,15 @@ test('docs reflect current launcher and release surfaces', () => {
   expect(changelogContents).toContain('v0.5.1 (2026-03-09)');
 });
 
+test('docs dev server links version navigation to local dev routes', () => {
+  expect(docsPackageContents).toContain('scripts/build-versioned-docs.ts');
+  expect(docsPackageContents).toContain(
+    'SUBMINER_DOCS_VERSION_LINK_ORIGIN=local bun run ../scripts/build-versioned-docs.ts',
+  );
+  expect(docsPackageContents).toContain('SUBMINER_DOCS_VERSION_LINK_ORIGIN=local');
+  expect(docsPackageContents).toContain('SUBMINER_DOCS_VERSION_MANIFEST');
+});
+
 test('docs changelog keeps the current minor release headings aligned with the root changelog', () => {
   const docsHeadings = extractCurrentMinorHeadings(changelogContents);
   expect(docsHeadings.length).toBeGreaterThan(0);

docs-site/package.json

@@ -5,10 +5,10 @@
   "description": "In-repo VitePress documentation site for SubMiner",
   "packageManager": "bun@1.3.5",
   "scripts": {
-    "docs:dev": "VITE_EXTRA_EXTENSIONS=jsonc vitepress dev --host 0.0.0.0 --port 5173 --strictPort",
+    "docs:dev": "SUBMINER_DOCS_VERSION_LINK_ORIGIN=local bun run ../scripts/build-versioned-docs.ts && SUBMINER_DOCS_VERSION_LINK_ORIGIN=local SUBMINER_DOCS_VERSION_MANIFEST=\"$(bun run ../scripts/print-docs-version-manifest.ts)\" VITE_EXTRA_EXTENSIONS=jsonc vitepress dev --host 0.0.0.0 --port 5173 --strictPort",
     "docs:build": "VITE_EXTRA_EXTENSIONS=jsonc vitepress build",
     "docs:preview": "VITE_EXTRA_EXTENSIONS=jsonc vitepress preview --host 0.0.0.0 --port 4173 --strictPort",
-    "test": "bun test plausible.test.ts index.assets.test.ts docs-sync.test.ts seo.test.ts ../scripts/docs-versioning.test.ts"
+    "test": "bun test plausible.test.ts index.assets.test.ts docs-sync.test.ts seo.test.ts .vitepress/theme/status-line.test.ts ../scripts/docs-versioning.test.ts"
   },
   "dependencies": {
     "@catppuccin/vitepress": "^0.1.2",

docs-site/plausible.test.ts

@@ -41,3 +41,28 @@ test('versioned docs reuse current VitePress internals for old page snapshots',
   expect(versionedBuildContents).toContain("cpSync(join(currentDocsSite, '.vitepress')");
   expect(versionedBuildContents).toContain('overlayCurrentVitePress(snapshotDocsSite)');
 });
+
+test('versioned docs build reports archive cache hits and rebuilds', () => {
+  expect(versionedBuildContents).toContain(
+    'console.info(`[docs] archive cache key ${archiveCacheKey.slice(0, 12)}`)',
+  );
+  expect(versionedBuildContents).toContain('console.info(`[docs] cache hit ${version}`)');
+  expect(versionedBuildContents).toContain('console.info(`[docs] rebuilding archive ${version}`)');
+});
+
+test('versioned docs build deduplicates public assets and prunes stale workspaces', () => {
+  expect(versionedBuildContents).toContain('dedupeVersionedPublicAssets({');
+  expect(versionedBuildContents).toContain('pruneArchiveCacheGenerations({');
+  expect(versionedBuildContents).toContain('rmSync(buildRoot, { recursive: true, force: true });');
+});
+
+test('versioned docs archive cache key ignores generated and test-only files', () => {
+  expect(versionedBuildContents).toContain('isSharedInternalsHashIgnoredPath(path)');
+  expect(versionedBuildContents).toContain('|| /\\.test\\.[cm]?[jt]s$/.test(path)');
+  expect(versionedBuildContents).toContain('process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN');
+  expect(versionedBuildContents).not.toContain('hash.update(String(stat.mode))');
+});
+
+test('docs builds exclude the internal README from VitePress page entries', () => {
+  expect(docsConfigContents).toContain("srcExclude: ['subagents/**', 'README.md']");
+});

docs-site/seo.test.ts

@@ -1,7 +1,13 @@
 import { expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import type { TransformContext } from 'vitepress';
 import docsConfig from './.vitepress/config';
 
+const docsSiteDir = fileURLToPath(new URL('.', import.meta.url));
+
 function makeTransformContext(page: string): TransformContext {
   return {
     page,
@@ -79,6 +85,343 @@ test('latest stable archive canonical points to root equivalent', async () => {
   process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
 });
 
+test('stable archive theme links stay on the selected version', async () => {
+  const previousCwd = process.cwd();
+  const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
+  const previousBase = process.env.SUBMINER_DOCS_BASE;
+  const previousVersion = process.env.SUBMINER_DOCS_VERSION;
+  const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
+  const previousManifest = process.env.SUBMINER_DOCS_VERSION_MANIFEST;
+  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
+  process.chdir(docsSiteDir);
+  process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
+  process.env.SUBMINER_DOCS_BASE = '/v/0.12.0/';
+  process.env.SUBMINER_DOCS_VERSION = 'v0.12.0';
+  process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
+  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'production';
+  process.env.SUBMINER_DOCS_VERSION_MANIFEST = JSON.stringify({
+    latestStable: 'v0.14.0',
+    channels: [
+      { label: 'Latest stable', path: '/' },
+      { label: 'main', path: '/main/' },
+    ],
+    versions: [
+      { version: 'v0.14.0', path: '/v/0.14.0/' },
+      { version: 'v0.12.0', path: '/v/0.12.0/' },
+    ],
+  });
+  try {
+    const { default: archiveConfig } = await import('./.vitepress/config?stable-archive-links');
+
+    const nav = archiveConfig.themeConfig?.nav as Array<{
+      text: string;
+      link?: string;
+      items?: Array<{ text: string; link: string }>;
+    }>;
+    const sidebar = archiveConfig.themeConfig?.sidebar as Array<{
+      text: string;
+      items?: Array<{ text: string; link: string }>;
+    }>;
+    const configurationNav = nav.find((item) => item.text === 'Configuration');
+    const versionNav = nav.find((item) => item.text === 'v0.12.0');
+    const referenceSidebar = sidebar.find((item) => item.text === 'Reference');
+    const configurationSidebar = referenceSidebar?.items?.find(
+      (item) => item.text === 'Configuration',
+    );
+
+    expect(configurationNav?.link).toBe('/configuration');
+    expect(configurationSidebar?.link).toBe('/configuration');
+    expect(versionNav?.items).toContainEqual({
+      text: 'Latest stable (v0.14.0)',
+      link: 'https://docs.subminer.moe/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'main',
+      link: 'https://docs.subminer.moe/main/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'v0.14.0',
+      link: 'https://docs.subminer.moe/v/0.14.0/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'v0.12.0',
+      link: 'https://docs.subminer.moe/v/0.12.0/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(archiveConfig.themeConfig?.logo).toEqual({
+      light: '/assets/SubMiner.png',
+      dark: '/assets/SubMiner.png',
+    });
+  } finally {
+    process.chdir(previousCwd);
+    process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
+    process.env.SUBMINER_DOCS_BASE = previousBase;
+    process.env.SUBMINER_DOCS_VERSION = previousVersion;
+    process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
+    process.env.SUBMINER_DOCS_VERSION_MANIFEST = previousManifest;
+    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
+  }
+});
+
+test('local stable archive version links stay on the dev server', async () => {
+  const previousCwd = process.cwd();
+  const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
+  const previousBase = process.env.SUBMINER_DOCS_BASE;
+  const previousVersion = process.env.SUBMINER_DOCS_VERSION;
+  const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
+  const previousManifest = process.env.SUBMINER_DOCS_VERSION_MANIFEST;
+  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
+  process.chdir(docsSiteDir);
+  process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
+  process.env.SUBMINER_DOCS_BASE = '/v/0.10.0/';
+  process.env.SUBMINER_DOCS_VERSION = 'v0.10.0';
+  process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
+  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'local';
+  process.env.SUBMINER_DOCS_VERSION_MANIFEST = JSON.stringify({
+    latestStable: 'v0.14.0',
+    channels: [
+      { label: 'Latest stable', path: '/' },
+      { label: 'main', path: '/main/' },
+    ],
+    versions: [
+      { version: 'v0.14.0', path: '/v/0.14.0/' },
+      { version: 'v0.10.0', path: '/v/0.10.0/' },
+    ],
+  });
+  try {
+    const { default: archiveConfig } = await import('./.vitepress/config?local-archive-links');
+
+    const nav = archiveConfig.themeConfig?.nav as Array<{
+      text: string;
+      items?: Array<{ text: string; link: string }>;
+    }>;
+    const versionNav = nav.find((item) => item.text === 'v0.10.0');
+
+    expect(versionNav?.items).toContainEqual({
+      text: 'Latest stable (v0.14.0)',
+      link: '../../',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'main',
+      link: '../../main/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'v0.14.0',
+      link: '../0.14.0/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'v0.10.0',
+      link: './',
+      target: '_self',
+      noIcon: true,
+    });
+  } finally {
+    process.chdir(previousCwd);
+    process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
+    process.env.SUBMINER_DOCS_BASE = previousBase;
+    process.env.SUBMINER_DOCS_VERSION = previousVersion;
+    process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
+    process.env.SUBMINER_DOCS_VERSION_MANIFEST = previousManifest;
+    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
+  }
+});
+
+test('dev docs version links use local targets for version route testing', async () => {
+  const previousCwd = process.cwd();
+  const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
+  const previousBase = process.env.SUBMINER_DOCS_BASE;
+  const previousVersion = process.env.SUBMINER_DOCS_VERSION;
+  const previousLatest = process.env.SUBMINER_DOCS_LATEST_STABLE;
+  const previousManifest = process.env.SUBMINER_DOCS_VERSION_MANIFEST;
+  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
+  process.chdir(docsSiteDir);
+  delete process.env.SUBMINER_DOCS_CHANNEL;
+  delete process.env.SUBMINER_DOCS_BASE;
+  delete process.env.SUBMINER_DOCS_VERSION;
+  delete process.env.SUBMINER_DOCS_LATEST_STABLE;
+  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'local';
+  process.env.SUBMINER_DOCS_VERSION_MANIFEST = JSON.stringify({
+    latestStable: 'v0.14.0',
+    channels: [
+      { label: 'Latest stable', path: '/' },
+      { label: 'main', path: '/main/' },
+    ],
+    versions: [
+      { version: 'v0.14.0', path: '/v/0.14.0/' },
+      { version: 'v0.12.0', path: '/v/0.12.0/' },
+      { version: 'v0.11.2', path: '/v/0.11.2/' },
+    ],
+  });
+  try {
+    const { default: devConfig } = await import('./.vitepress/config?dev-version-links');
+
+    const nav = devConfig.themeConfig?.nav as Array<{
+      text: string;
+      items?: Array<{ text: string; link: string }>;
+    }>;
+    const versionNav = nav.find((item) => item.text === 'v0.14.0');
+
+    expect(versionNav?.items).toContainEqual({
+      text: 'Latest stable (v0.14.0)',
+      link: '/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'main',
+      link: '/main/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items).toContainEqual({
+      text: 'v0.12.0',
+      link: '/v/0.12.0/',
+      target: '_self',
+      noIcon: true,
+    });
+    expect(versionNav?.items?.map((item) => item.text)).toEqual([
+      'Latest stable (v0.14.0)',
+      'main',
+      'v0.14.0',
+      'v0.12.0',
+      'v0.11.2',
+    ]);
+  } finally {
+    process.chdir(previousCwd);
+    process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
+    process.env.SUBMINER_DOCS_BASE = previousBase;
+    process.env.SUBMINER_DOCS_VERSION = previousVersion;
+    process.env.SUBMINER_DOCS_LATEST_STABLE = previousLatest;
+    process.env.SUBMINER_DOCS_VERSION_MANIFEST = previousManifest;
+    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
+  }
+});
+
+test('dev server redirects unserved version routes to production docs', () => {
+  let routeHandler:
+    | ((req: { url?: string }, res: DevRedirectResponse, next: () => void) => void)
+    | undefined;
+  const fakeServer = {
+    middlewares: {
+      use(handler: typeof routeHandler) {
+        routeHandler = handler;
+      },
+    },
+  };
+  const plugins = Array.isArray(docsConfig.vite?.plugins)
+    ? docsConfig.vite.plugins
+    : [docsConfig.vite?.plugins].filter(Boolean);
+  const redirectPlugin = plugins.find(
+    (plugin): plugin is { name: string; configureServer: (server: never) => void } =>
+      Boolean(plugin) &&
+      typeof plugin === 'object' &&
+      'name' in plugin &&
+      plugin.name === 'subminer-docs-local-version-redirects' &&
+      'configureServer' in plugin,
+  );
+  expect(redirectPlugin).toBeDefined();
+  redirectPlugin?.configureServer(fakeServer as never);
+
+  const response = new DevRedirectResponse();
+  let nextCalled = false;
+  routeHandler?.({ url: '/v/0.14.0/?from=dev' }, response, () => {
+    nextCalled = true;
+  });
+
+  expect(nextCalled).toBe(false);
+  expect(response.statusCode).toBe(302);
+  expect(response.headers.location).toBe('https://docs.subminer.moe/v/0.14.0/?from=dev');
+
+  const rootResponse = new DevRedirectResponse();
+  routeHandler?.({ url: '/configuration' }, rootResponse, () => {
+    nextCalled = true;
+  });
+  expect(rootResponse.ended).toBe(false);
+  expect(nextCalled).toBe(true);
+});
+
+test('dev server serves local archive files for local version links', async () => {
+  const previousVersionLinkOrigin = process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN;
+  const previousArchiveDir = process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR;
+  const archiveDir = mkdtempSync(join(tmpdir(), 'subminer-docs-archive-'));
+  mkdirSync(join(archiveDir, 'v/0.14.0'), { recursive: true });
+  writeFileSync(join(archiveDir, 'v/0.14.0/index.html'), '<h1>local archive</h1>');
+  process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = 'local';
+  process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR = archiveDir;
+  try {
+    const { default: localDevConfig } = await import('./.vitepress/config?local-dev-redirects');
+    let routeHandler:
+      | ((req: { url?: string }, res: DevRedirectResponse, next: () => void) => void)
+      | undefined;
+    const fakeServer = {
+      middlewares: {
+        use(handler: typeof routeHandler) {
+          routeHandler = handler;
+        },
+      },
+    };
+    const plugins = Array.isArray(localDevConfig.vite?.plugins)
+      ? localDevConfig.vite.plugins
+      : [localDevConfig.vite?.plugins].filter(Boolean);
+    const redirectPlugin = plugins.find(
+      (plugin): plugin is { name: string; configureServer: (server: never) => void } =>
+        Boolean(plugin) &&
+        typeof plugin === 'object' &&
+        'name' in plugin &&
+        plugin.name === 'subminer-docs-local-version-redirects' &&
+        'configureServer' in plugin,
+    );
+    redirectPlugin?.configureServer(fakeServer as never);
+
+    const response = new DevRedirectResponse();
+    let nextCalled = false;
+    routeHandler?.({ url: '/v/0.14.0/?from=dev' }, response, () => {
+      nextCalled = true;
+    });
+
+    expect(nextCalled).toBe(false);
+    expect(response.statusCode).toBe(200);
+    expect(response.headers['content-type']).toBe('text/html; charset=utf-8');
+    expect(response.headers.location).toBeUndefined();
+    expect(response.body).toBe('<h1>local archive</h1>');
+  } finally {
+    process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN = previousVersionLinkOrigin;
+    process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR = previousArchiveDir;
+    rmSync(archiveDir, { recursive: true, force: true });
+  }
+});
+
+class DevRedirectResponse {
+  statusCode = 200;
+  headers: Record<string, string> = {};
+  ended = false;
+  body = '';
+
+  setHeader(name: string, value: string) {
+    this.headers[name.toLowerCase()] = value;
+  }
+
+  end(chunk?: string | Uint8Array) {
+    if (chunk) {
+      this.body = typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);
+    }
+    this.ended = true;
+  }
+}
+
 test('docs sitemap excludes duplicate README page from indexable URLs', async () => {
   const items = [{ url: '' }, { url: 'README' }, { url: 'usage' }];