[codex] add versioned Pages deployment (#73)

docs-site/.vitepress/config.ts

@@ -1,3 +1,7 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { DefaultTheme, HeadConfig, TransformContext, UserConfig } from 'vitepress';
+
 const DOCS_HOSTNAME = 'https://docs.subminer.moe';
 const PLAUSIBLE_PROXY_HOSTNAME = 'https://worker.sudacode.com';
 const PLAUSIBLE_SITE_SCRIPT_PATH = '/js/pa-h28Pn9ppgTJRmiSJlyPT6.js';
@@ -7,20 +11,212 @@ const PLAUSIBLE_INIT_SCRIPT = [
   `plausible.init({ endpoint: '${PLAUSIBLE_ENDPOINT}' });`,
 ].join('\n');
 
-function pageToCanonicalHref(page: string): string | null {
+type DocsChannel = 'stable-root' | 'stable-archive' | 'main';
+
+type VersionManifest = {
+  latestStable: string;
+  channels: Array<{ label: string; path: string }>;
+  versions: Array<{ version: string; path: string }>;
+};
+
+const base = normalizeBase(process.env.SUBMINER_DOCS_BASE ?? '/');
+const outDir = process.env.SUBMINER_DOCS_OUT_DIR;
+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);
+
+function normalizeBase(value: string): string {
+  if (!value || value === '/') return '/';
+  return `/${value.replace(/^\/+|\/+$/g, '')}/`;
+}
+
+function normalizeChannel(value: string | undefined): DocsChannel {
+  if (value === 'main' || value === 'stable-archive') return value;
+  return 'stable-root';
+}
+
+function parseVersionManifest(value: string | undefined): VersionManifest {
+  if (!value) {
+    return {
+      latestStable,
+      channels: [
+        { label: 'Latest stable', path: '/' },
+        { label: 'main', path: '/main/' },
+      ],
+      versions: [{ version: latestStable, path: `/v/${latestStable.replace(/^v/, '')}/` }],
+    };
+  }
+
+  return JSON.parse(value) as VersionManifest;
+}
+
+function withDocsBase(path: string): string {
+  if (/^[a-z]+:\/\//i.test(path)) return path;
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  if (base === '/') return normalizedPath;
+  return `${base.replace(/\/$/, '')}${normalizedPath}`;
+}
+
+function pageToRoute(page: string): string | null {
   if (page === '404.md') return null;
 
   const route = page
     .replace(/(^|\/)index\.md$/, '')
     .replace(/\.md$/, '')
     .replace(/\/$/, '');
-  return route ? `${DOCS_HOSTNAME}/${route}` : `${DOCS_HOSTNAME}/`;
+  return route ? `/${route}` : '/';
 }
 
-export default {
+function pageToCanonicalHref(page: string): string | null {
+  const route = pageToRoute(page);
+  if (!route) return null;
+
+  if (channel === 'main') {
+    return `${DOCS_HOSTNAME}${canonicalRouteWithBase(route)}`;
+  }
+
+  if (channel === 'stable-archive' && docsVersion !== latestStable) {
+    return `${DOCS_HOSTNAME}${canonicalRouteWithBase(route)}`;
+  }
+
+  return route === '/' ? `${DOCS_HOSTNAME}/` : `${DOCS_HOSTNAME}${route}`;
+}
+
+function canonicalRouteWithBase(route: string): string {
+  const routeWithBase = withDocsBase(route);
+  return route === '/' ? routeWithBase : routeWithBase.replace(/\/$/, '');
+}
+
+function transformPageHead({ page }: TransformContext): HeadConfig[] {
+  const href = pageToCanonicalHref(page);
+  const head: HeadConfig[] = href ? [['link', { rel: 'canonical', href }]] : [];
+
+  if (channel === 'main') {
+    head.push(['meta', { name: 'robots', content: 'noindex,follow' }]);
+  }
+
+  return head;
+}
+
+function linkToPagePath(link: string): string | null {
+  if (!link.startsWith('/') || link.startsWith('/v/') || link.startsWith('/main/')) {
+    return null;
+  }
+
+  const withoutHash = link.split('#')[0] ?? '/';
+  const withoutQuery = withoutHash.split('?')[0] ?? '/';
+  const route = withoutQuery.replace(/^\/+|\/+$/g, '');
+  return route ? `${route}.md` : 'index.md';
+}
+
+function hasPageForLink(link: string): boolean {
+  const pagePath = linkToPagePath(link);
+  if (!pagePath) return true;
+  return existsSync(join(process.cwd(), pagePath));
+}
+
+function filterNav(items: DefaultTheme.NavItem[]): DefaultTheme.NavItem[] {
+  return items
+    .map((item) => {
+      if ('items' in item && item.items) {
+        return { ...item, items: filterNav(item.items as DefaultTheme.NavItem[]) };
+      }
+      if ('link' in item && item.link && !hasPageForLink(item.link)) {
+        return null;
+      }
+      return item;
+    })
+    .filter((item): item is DefaultTheme.NavItem => Boolean(item));
+}
+
+function filterSidebar(items: DefaultTheme.SidebarItem[]): DefaultTheme.SidebarItem[] {
+  return items
+    .map((item) => {
+      const filteredChildren = item.items ? filterSidebar(item.items) : undefined;
+      if (item.link && !hasPageForLink(item.link)) return null;
+      if (item.items && filteredChildren?.length === 0 && !item.link) return null;
+      return { ...item, items: filteredChildren };
+    })
+    .filter((item): item is DefaultTheme.SidebarItem => Boolean(item));
+}
+
+const versionItems = [
+  {
+    text: `Latest stable (${versionManifest.latestStable})`,
+    link: '/',
+  },
+  ...versionManifest.channels
+    .filter((entry) => entry.label !== 'Latest stable')
+    .map((entry) => ({ text: entry.label, link: entry.path })),
+  ...versionManifest.versions.map((entry) => ({
+    text: entry.version,
+    link: entry.path,
+  })),
+];
+
+const nav: DefaultTheme.NavItem[] = [
+  { text: 'Home', link: '/' },
+  { text: 'Get Started', link: '/installation' },
+  { text: 'Mining', link: '/mining-workflow' },
+  { text: 'Configuration', link: '/configuration' },
+  { text: 'Changelog', link: '/changelog' },
+  { text: 'Troubleshooting', link: '/troubleshooting' },
+  { text: docsVersion ?? (channel === 'main' ? 'main' : latestStable), items: versionItems },
+];
+
+const sidebar: DefaultTheme.SidebarItem[] = [
+  {
+    text: 'Getting Started',
+    items: [
+      { text: 'Overview', link: '/' },
+      { text: 'Installation', link: '/installation' },
+      { text: 'Usage', link: '/usage' },
+      { text: 'Mining Workflow', link: '/mining-workflow' },
+      { text: 'Launcher Script', link: '/launcher-script' },
+    ],
+  },
+  {
+    text: 'Reference',
+    items: [
+      { text: 'Configuration', link: '/configuration' },
+      { text: 'Keyboard Shortcuts', link: '/shortcuts' },
+      { text: 'Subtitle Annotations', link: '/subtitle-annotations' },
+      { text: 'Subtitle Sidebar', link: '/subtitle-sidebar' },
+      { text: 'Immersion Tracking', link: '/immersion-tracking' },
+      { text: 'Troubleshooting', link: '/troubleshooting' },
+    ],
+  },
+  {
+    text: 'Integrations',
+    items: [
+      { text: 'MPV Plugin', link: '/mpv-plugin' },
+      { text: 'Anki', link: '/anki-integration' },
+      { text: 'Jellyfin', link: '/jellyfin-integration' },
+      { text: 'YouTube', link: '/youtube-integration' },
+      { text: 'Jimaku', link: '/jimaku-integration' },
+      { text: 'AniList', link: '/anilist-integration' },
+      { text: 'Character Dictionary', link: '/character-dictionary' },
+    ],
+  },
+  {
+    text: 'Development',
+    items: [
+      { text: 'Building & Testing', link: '/development' },
+      { text: 'Architecture', link: '/architecture' },
+      { text: 'IPC + Runtime Contracts', link: '/ipc-contracts' },
+      { text: 'WebSocket + Texthooker API', link: '/websocket-texthooker-api' },
+      { text: 'Changelog', link: '/changelog' },
+    ],
+  },
+];
+
+const config: UserConfig = {
   title: 'SubMiner Docs',
   description:
     'SubMiner: an MPV immersion-mining overlay with Yomitan and AnkiConnect integration.',
+  base,
+  ...(outDir ? { outDir } : {}),
   head: [
     ['link', { rel: 'preconnect', href: PLAUSIBLE_PROXY_HOSTNAME }],
     [
@@ -31,13 +227,13 @@ export default {
       },
     ],
     ['script', {}, PLAUSIBLE_INIT_SCRIPT],
-    ['link', { rel: 'icon', href: '/favicon.ico', sizes: 'any' }],
+    ['link', { rel: 'icon', href: withDocsBase('/favicon.ico'), sizes: 'any' }],
     [
       'link',
       {
         rel: 'icon',
         type: 'image/png',
-        href: '/favicon-32x32.png',
+        href: withDocsBase('/favicon-32x32.png'),
         sizes: '32x32',
       },
     ],
@@ -46,7 +242,7 @@ export default {
       {
         rel: 'icon',
         type: 'image/png',
-        href: '/favicon-16x16.png',
+        href: withDocsBase('/favicon-16x16.png'),
         sizes: '16x16',
       },
     ],
@@ -54,7 +250,7 @@ export default {
       'link',
       {
         rel: 'apple-touch-icon',
-        href: '/apple-touch-icon.png',
+        href: withDocsBase('/apple-touch-icon.png'),
         sizes: '180x180',
       },
     ],
@@ -70,10 +266,7 @@ export default {
       );
     },
   },
-  transformHead({ page }) {
-    const href = pageToCanonicalHref(page);
-    return href ? [['link', { rel: 'canonical', href }]] : [];
-  },
+  transformHead: transformPageHead,
   lastUpdated: true,
   srcExclude: ['subagents/**'],
   markdown: {
@@ -84,63 +277,12 @@ export default {
   },
   themeConfig: {
     logo: {
-      light: '/assets/SubMiner.png',
-      dark: '/assets/SubMiner.png',
+      light: withDocsBase('/assets/SubMiner.png'),
+      dark: withDocsBase('/assets/SubMiner.png'),
     },
     siteTitle: 'SubMiner Docs',
-    nav: [
-      { text: 'Home', link: '/' },
-      { text: 'Get Started', link: '/installation' },
-      { text: 'Mining', link: '/mining-workflow' },
-      { text: 'Configuration', link: '/configuration' },
-      { text: 'Changelog', link: '/changelog' },
-      { text: 'Troubleshooting', link: '/troubleshooting' },
-    ],
-    sidebar: [
-      {
-        text: 'Getting Started',
-        items: [
-          { text: 'Overview', link: '/' },
-          { text: 'Installation', link: '/installation' },
-          { text: 'Usage', link: '/usage' },
-          { text: 'Mining Workflow', link: '/mining-workflow' },
-          { text: 'Launcher Script', link: '/launcher-script' },
-        ],
-      },
-      {
-        text: 'Reference',
-        items: [
-          { text: 'Configuration', link: '/configuration' },
-          { text: 'Keyboard Shortcuts', link: '/shortcuts' },
-          { text: 'Subtitle Annotations', link: '/subtitle-annotations' },
-          { text: 'Subtitle Sidebar', link: '/subtitle-sidebar' },
-          { text: 'Immersion Tracking', link: '/immersion-tracking' },
-          { text: 'Troubleshooting', link: '/troubleshooting' },
-        ],
-      },
-      {
-        text: 'Integrations',
-        items: [
-          { text: 'MPV Plugin', link: '/mpv-plugin' },
-          { text: 'Anki', link: '/anki-integration' },
-          { text: 'Jellyfin', link: '/jellyfin-integration' },
-          { text: 'YouTube', link: '/youtube-integration' },
-          { text: 'Jimaku', link: '/jimaku-integration' },
-          { text: 'AniList', link: '/anilist-integration' },
-          { text: 'Character Dictionary', link: '/character-dictionary' },
-        ],
-      },
-      {
-        text: 'Development',
-        items: [
-          { text: 'Building & Testing', link: '/development' },
-          { text: 'Architecture', link: '/architecture' },
-          { text: 'IPC + Runtime Contracts', link: '/ipc-contracts' },
-          { text: 'WebSocket + Texthooker API', link: '/websocket-texthooker-api' },
-          { text: 'Changelog', link: '/changelog' },
-        ],
-      },
-    ],
+    nav: filterNav(nav),
+    sidebar: filterSidebar(sidebar),
     search: {
       provider: 'local',
     },
@@ -159,3 +301,5 @@ export default {
     socialLinks: [{ icon: 'github', link: 'https://github.com/ksyasuda/SubMiner' }],
   },
 };
+
+export default config;

docs-site/.vitepress/theme/tui-theme.css

@@ -5,7 +5,7 @@
 
 @font-face {
   font-family: 'M PLUS 1';
-  src: url('/assets/fonts/Mplus1-Medium.ttf') format('truetype');
+  src: url('../../public/assets/fonts/Mplus1-Medium.ttf') format('truetype');
   font-weight: 500;
   font-style: normal;
   font-display: swap;
@@ -13,7 +13,7 @@
 
 @font-face {
   font-family: 'Manrope Default';
-  src: url('/assets/fonts/manrope-latin-600-normal.ttf') format('truetype');
+  src: url('../../public/assets/fonts/manrope-latin-600-normal.ttf') format('truetype');
   font-weight: 600;
   font-style: normal;
   font-display: swap;

docs-site/README.md

@@ -30,9 +30,16 @@ bun run docs:dev
 ## Cloudflare Pages
 
 - Git repo: `ksyasuda/SubMiner`
-- Root directory: `docs-site`
-- Build command: `bun run docs:build`
-- Build output directory: `.vitepress/dist`
-- Build watch paths: `docs-site/*`
+- Production branch: `main`
+- Automatic production and preview deployments: disabled
+- Custom domain: `docs.subminer.moe` attached to Production
+- Deployment path: GitHub Actions direct upload with Wrangler
 
-Cloudflare Pages watch paths use a single `*` wildcard for monorepo subdirectories. `docs-site/*` matches nested files under the docs site; `docs-site/**` can cause docs-only pushes to be skipped.
+The public docs root is stable-only:
+
+- `/` serves the latest stable release docs.
+- `/main/` serves development docs from `main` and is marked `noindex,follow`.
+- `/v/<version>/` serves stable release archives.
+- Prerelease tags do not update the docs site.
+
+Keep Cloudflare Git auto-deploy disabled. The production deploy is `.github/workflows/docs-pages.yml`, which uploads `.tmp/docs-versioned-site` with `--branch main` so tag-triggered runs update Production instead of creating preview deployments.

docs-site/configuration.md

@@ -4,6 +4,10 @@ outline: [2, 3]
 
 # Configuration
 
+<script setup>
+import { withBase } from 'vitepress';
+</script>
+
 Settings are stored in `$XDG_CONFIG_HOME/SubMiner/config.jsonc` (or `~/.config/SubMiner/config.jsonc` when `XDG_CONFIG_HOME` is unset).
 On Windows, the default path is `%APPDATA%\SubMiner\config.jsonc`.
 When both files exist, SubMiner prefers `config.jsonc` over `config.json`.
@@ -1044,12 +1048,12 @@ To refresh roughly once per day, set:
 `deleteDuplicateInAuto` controls whether `auto` mode deletes the duplicate after merge (default: `true`). In `manual` mode, the popup asks each time whether to delete the duplicate.
 When the manual merge popup opens, SubMiner pauses playback and closes any open Yomitan popup first so the merge flow can take focus.
 
-<video controls playsinline preload="metadata" poster="/assets/kiku-integration-poster.jpg" style="width: 100%; max-width: 960px;">
-  <source :src="'/assets/kiku-integration.webm'" type="video/webm" />
+<video controls playsinline preload="metadata" :poster="withBase('/assets/kiku-integration-poster.jpg')" style="width: 100%; max-width: 960px;">
+  <source :src="withBase('/assets/kiku-integration.webm')" type="video/webm" />
   Your browser does not support the video tag.
 </video>
 
-<a :href="'/assets/kiku-integration.webm'" target="_blank" rel="noreferrer">Open demo in a new tab</a>
+<a :href="withBase('/assets/kiku-integration.webm')" target="_blank" rel="noreferrer">Open demo in a new tab</a>
 
 ## External Integrations
 

docs-site/demos.md

@@ -3,6 +3,8 @@
 Short recordings of SubMiner's key features and integrations from real playback sessions.
 
 <script setup>
+import { withBase } from 'vitepress';
+
 const v = '20260301-1';
 </script>
 
@@ -10,11 +12,11 @@ const v = '20260301-1';
 
 Mine vocabulary cards from Yomitan or directly from subtitle lines. SubMiner automatically attaches the sentence, a timing-accurate audio clip, a screenshot, and a translation.
 
-<video controls playsinline preload="metadata" :poster="`/assets/minecard-poster.jpg?v=${demoAssetVersion}`">
-  <source :src="`/assets/minecard.webm?v=${demoAssetVersion}`" type="video/webm" />
-  <source :src="`/assets/minecard.mp4?v=${demoAssetVersion}`" type="video/mp4" />
-  <a :href="`/assets/minecard.webm?v=${demoAssetVersion}`" target="_blank" rel="noreferrer">
-    <img :src="`/assets/minecard.webp?v=${demoAssetVersion}`" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />
+<video controls playsinline preload="metadata" :poster="withBase(`/assets/minecard-poster.jpg?v=${v}`)">
+  <source :src="withBase(`/assets/minecard.webm?v=${v}`)" type="video/webm" />
+  <source :src="withBase(`/assets/minecard.mp4?v=${v}`)" type="video/mp4" />
+  <a :href="withBase(`/assets/minecard.webm?v=${v}`)" target="_blank" rel="noreferrer">
+    <img :src="withBase(`/assets/minecard.webp?v=${v}`)" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />
   </a>
 </video>
 
@@ -25,9 +27,9 @@ Mine vocabulary cards from Yomitan or directly from subtitle lines. SubMiner aut
 
 Search and download subtitles from Jimaku, then automatically synchronize them with alass or ffsubsync — all from within SubMiner.
 
-<!-- <video controls playsinline preload="metadata" :poster="`/assets/demos/subtitle-sync-poster.jpg?v=${v}`">
-  <source :src="`/assets/demos/subtitle-sync.webm?v=${v}`" type="video/webm" />
-  <source :src="`/assets/demos/subtitle-sync.mp4?v=${v}`" type="video/mp4" />
+<!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/subtitle-sync-poster.jpg?v=${v}`)">
+  <source :src="withBase(`/assets/demos/subtitle-sync.webm?v=${v}`)" type="video/webm" />
+  <source :src="withBase(`/assets/demos/subtitle-sync.mp4?v=${v}`)" type="video/mp4" />
 </video> -->
 
 ::: info VIDEO COMING SOON
@@ -37,9 +39,9 @@ Search and download subtitles from Jimaku, then automatically synchronize them w
 
 Browse your Jellyfin library, cast to devices, and launch playback directly from SubMiner. Watch progress syncs back to your Jellyfin server.
 
-<!-- <video controls playsinline preload="metadata" :poster="`/assets/demos/jellyfin-poster.jpg?v=${v}`">
-  <source :src="`/assets/demos/jellyfin.webm?v=${v}`" type="video/webm" />
-  <source :src="`/assets/demos/jellyfin.mp4?v=${v}`" type="video/mp4" />
+<!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/jellyfin-poster.jpg?v=${v}`)">
+  <source :src="withBase(`/assets/demos/jellyfin.webm?v=${v}`)" type="video/webm" />
+  <source :src="withBase(`/assets/demos/jellyfin.mp4?v=${v}`)" type="video/mp4" />
 </video> -->
 
 ::: info VIDEO COMING SOON
@@ -49,9 +51,9 @@ Browse your Jellyfin library, cast to devices, and launch playback directly from
 
 Open subtitles in an external texthooker page for use with browser-based tools and extensions alongside the overlay.
 
-<!-- <video controls playsinline preload="metadata" :poster="`/assets/demos/texthooker-poster.jpg?v=${v}`">
-  <source :src="`/assets/demos/texthooker.webm?v=${v}`" type="video/webm" />
-  <source :src="`/assets/demos/texthooker.mp4?v=${v}`" type="video/mp4" />
+<!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/texthooker-poster.jpg?v=${v}`)">
+  <source :src="withBase(`/assets/demos/texthooker.webm?v=${v}`)" type="video/webm" />
+  <source :src="withBase(`/assets/demos/texthooker.mp4?v=${v}`)" type="video/mp4" />
 </video> -->
 
 ::: info VIDEO COMING SOON

docs-site/development.md

@@ -113,6 +113,14 @@ bun run docs:test
 bun run docs:build
 ```
 
+For production docs routing, run the versioned build:
+
+```bash
+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.
+
 Focused commands:
 
 ```bash

docs-site/docs-sync.test.ts

@@ -37,13 +37,13 @@ test('docs reflect current launcher and release surfaces', () => {
 
   expect(mpvPluginContents).toContain('\\\\.\\pipe\\subminer-socket');
 
-  expect(readmeContents).toContain('Root directory: `docs-site`');
-  expect(readmeContents).toContain('Build output directory: `.vitepress/dist`');
-  expect(readmeContents).toContain('Build watch paths: `docs-site/*`');
+  expect(readmeContents).toContain('Automatic production and preview deployments: disabled');
+  expect(readmeContents).toContain('/main/');
+  expect(readmeContents).toContain('GitHub Actions direct upload with Wrangler');
   expect(developmentContents).not.toContain('../subminer-docs');
   expect(developmentContents).toContain('bun run docs:build');
   expect(developmentContents).toContain('bun run docs:test');
-  expect(developmentContents).toContain('Build watch paths: `docs-site/*`');
+  expect(developmentContents).toContain('bun run docs:build:versioned');
   expect(developmentContents).not.toContain('test:subtitle:dist');
   expect(developmentContents).toContain('bun run build:win');
 

docs-site/index.assets.test.ts

@@ -7,18 +7,18 @@ const docsIndexContents = readFileSync(docsIndexPath, 'utf8');
 test('docs demo media uses shared cache-busting asset version token', () => {
   expect(docsIndexContents).toMatch(/const demoAssetVersion = ['"][^'"]+['"]/);
   expect(docsIndexContents).toContain(
-    ':poster="`/assets/minecard-poster.jpg?v=${demoAssetVersion}`"',
+    ':poster="withBase(`/assets/minecard-poster.jpg?v=${demoAssetVersion}`)"',
   );
   expect(docsIndexContents).toContain(
-    '<source :src="`/assets/minecard.webm?v=${demoAssetVersion}`" type="video/webm" />',
+    '<source :src="withBase(`/assets/minecard.webm?v=${demoAssetVersion}`)" type="video/webm" />',
   );
   expect(docsIndexContents).toContain(
-    '<source :src="`/assets/minecard.mp4?v=${demoAssetVersion}`" type="video/mp4" />',
+    '<source :src="withBase(`/assets/minecard.mp4?v=${demoAssetVersion}`)" type="video/mp4" />',
   );
   expect(docsIndexContents).toContain(
-    '<a :href="`/assets/minecard.webm?v=${demoAssetVersion}`" target="_blank" rel="noreferrer">',
+    '<a :href="withBase(`/assets/minecard.webm?v=${demoAssetVersion}`)" target="_blank" rel="noreferrer">',
   );
   expect(docsIndexContents).toContain(
-    '<img :src="`/assets/minecard.webp?v=${demoAssetVersion}`" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />',
+    '<img :src="withBase(`/assets/minecard.webp?v=${demoAssetVersion}`)" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />',
   );
 });

docs-site/index.md

@@ -86,6 +86,8 @@ features:
 ---
 
 <script setup>
+import { withBase } from 'vitepress';
+
 const demoAssetVersion = '20260223-2';
 </script>
 
@@ -135,11 +137,11 @@ const demoAssetVersion = '20260223-2';
         <span class="demo-window__dot"></span>
         <span class="demo-window__title">subminer -- playback</span>
       </div>
-      <video controls playsinline preload="metadata" :poster="`/assets/minecard-poster.jpg?v=${demoAssetVersion}`">
-        <source :src="`/assets/minecard.webm?v=${demoAssetVersion}`" type="video/webm" />
-        <source :src="`/assets/minecard.mp4?v=${demoAssetVersion}`" type="video/mp4" />
-        <a :href="`/assets/minecard.webm?v=${demoAssetVersion}`" target="_blank" rel="noreferrer">
-          <img :src="`/assets/minecard.webp?v=${demoAssetVersion}`" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />
+      <video controls playsinline preload="metadata" :poster="withBase(`/assets/minecard-poster.jpg?v=${demoAssetVersion}`)">
+        <source :src="withBase(`/assets/minecard.webm?v=${demoAssetVersion}`)" type="video/webm" />
+        <source :src="withBase(`/assets/minecard.mp4?v=${demoAssetVersion}`)" type="video/mp4" />
+        <a :href="withBase(`/assets/minecard.webm?v=${demoAssetVersion}`)" target="_blank" rel="noreferrer">
+          <img :src="withBase(`/assets/minecard.webp?v=${demoAssetVersion}`)" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />
         </a>
       </video>
     </div>

docs-site/package.json

@@ -8,7 +8,7 @@
     "docs:dev": "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"
+    "test": "bun test plausible.test.ts index.assets.test.ts docs-sync.test.ts seo.test.ts ../scripts/docs-versioning.test.ts"
   },
   "dependencies": {
     "@catppuccin/vitepress": "^0.1.2",

docs-site/plausible.test.ts

@@ -4,9 +4,11 @@ import { readFileSync } from 'node:fs';
 const docsConfigPath = new URL('./.vitepress/config.ts', import.meta.url);
 const docsThemePath = new URL('./.vitepress/theme/index.ts', import.meta.url);
 const docsPackagePath = new URL('./package.json', import.meta.url);
+const versionedBuildPath = new URL('../scripts/build-versioned-docs.ts', import.meta.url);
 const docsConfigContents = readFileSync(docsConfigPath, 'utf8');
 const docsThemeContents = readFileSync(docsThemePath, 'utf8');
 const docsPackageContents = readFileSync(docsPackagePath, 'utf8');
+const versionedBuildContents = readFileSync(versionedBuildPath, 'utf8');
 
 test('docs site loads the docs.subminer.moe Plausible script through the analytics proxy', () => {
   expect(docsConfigContents).toContain("const DOCS_HOSTNAME = 'https://docs.subminer.moe'");
@@ -34,3 +36,8 @@ test('docs site loads the docs.subminer.moe Plausible script through the analyti
   expect(docsThemeContents).not.toContain('initPlausibleTracker');
   expect(docsPackageContents).not.toContain('@plausible-analytics/tracker');
 });
+
+test('versioned docs reuse current VitePress internals for old page snapshots', () => {
+  expect(versionedBuildContents).toContain("cpSync(join(currentDocsSite, '.vitepress')");
+  expect(versionedBuildContents).toContain('overlayCurrentVitePress(snapshotDocsSite)');
+});

docs-site/seo.test.ts

@@ -31,6 +31,54 @@ test('docs pages emit stable self-referential canonical URLs', async () => {
   expect(JSON.stringify(rootHead).toLowerCase()).not.toContain('noindex');
 });
 
+test('main docs canonical uses /main/ and emits noindex', async () => {
+  const previousChannel = process.env.SUBMINER_DOCS_CHANNEL;
+  const previousBase = process.env.SUBMINER_DOCS_BASE;
+  process.env.SUBMINER_DOCS_CHANNEL = 'main';
+  process.env.SUBMINER_DOCS_BASE = '/main/';
+  const { default: mainDocsConfig } = await import('./.vitepress/config?main-docs');
+
+  const head = await mainDocsConfig.transformHead?.(makeTransformContext('usage.md'));
+  const rootHead = await mainDocsConfig.transformHead?.(makeTransformContext('index.md'));
+
+  expect(head).toContainEqual([
+    'link',
+    { rel: 'canonical', href: 'https://docs.subminer.moe/main/usage' },
+  ]);
+  expect(rootHead).toContainEqual([
+    'link',
+    { rel: 'canonical', href: 'https://docs.subminer.moe/main/' },
+  ]);
+  expect(head).toContainEqual(['meta', { name: 'robots', content: 'noindex,follow' }]);
+
+  process.env.SUBMINER_DOCS_CHANNEL = previousChannel;
+  process.env.SUBMINER_DOCS_BASE = previousBase;
+});
+
+test('latest stable archive canonical points to root equivalent', async () => {
+  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;
+  process.env.SUBMINER_DOCS_CHANNEL = 'stable-archive';
+  process.env.SUBMINER_DOCS_BASE = '/v/0.14.0/';
+  process.env.SUBMINER_DOCS_VERSION = 'v0.14.0';
+  process.env.SUBMINER_DOCS_LATEST_STABLE = 'v0.14.0';
+  const { default: latestArchiveConfig } = await import('./.vitepress/config?latest-archive');
+
+  const head = await latestArchiveConfig.transformHead?.(makeTransformContext('usage.md'));
+
+  expect(head).toContainEqual([
+    'link',
+    { rel: 'canonical', href: 'https://docs.subminer.moe/usage' },
+  ]);
+
+  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;
+});
+
 test('docs sitemap excludes duplicate README page from indexable URLs', async () => {
   const items = [{ url: '' }, { url: 'README' }, { url: 'usage' }];