support release and dev docs

Author: clavery

.github/workflows/deploy-docs.yml

@@ -43,8 +43,33 @@ jobs:
       - name: Build packages
         run: pnpm -r run build
 
-      - name: Build documentation
+      - name: Get latest release tag
+        id: release
+        run: |
+          LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+          echo "tag=$LATEST_TAG" >> $GITHUB_OUTPUT
+          echo "exists=$([[ -n $LATEST_TAG ]] && echo true || echo false)" >> $GITHUB_OUTPUT
+
+      - name: Build main documentation
         run: pnpm run docs:build
+        env:
+          RELEASE_VERSION: ${{ steps.release.outputs.tag }}
+
+      - name: Build release documentation
+        if: steps.release.outputs.exists == 'true'
+        run: |
+          # Save main build
+          mv docs/.vitepress/dist docs/.vitepress/dist-main
+
+          # Checkout and build at release tag
+          git checkout ${{ steps.release.outputs.tag }}
+          pnpm install --frozen-lockfile
+          pnpm -r run build
+          RELEASE_VERSION=${{ steps.release.outputs.tag }} IS_RELEASE_BUILD=true pnpm run docs:build
+
+          # Combine: main at root, release in /release/
+          mv docs/.vitepress/dist docs/.vitepress/dist-main/release
+          mv docs/.vitepress/dist-main docs/.vitepress/dist
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

docs/.vitepress/config.mts

@@ -1,6 +1,33 @@
 import { defineConfig } from 'vitepress';
 import typedocSidebar from '../api/typedoc-sidebar.json';
 
+// Version configuration from environment
+const releaseVersion = process.env.RELEASE_VERSION || 'unreleased';
+const isReleaseBuild = process.env.IS_RELEASE_BUILD === 'true';
+
+// Base path for this build
+const basePath = '/b2c-developer-tooling/';
+
+// Build version dropdown items
+// Note: VitePress automatically prepends the base path to links, so we use root-relative paths
+function getVersionItems() {
+  if (isReleaseBuild) {
+    return [
+      { text: 'Development (main)', link: basePath },
+      { text: `Release (${releaseVersion})`, link: `${basePath}release/` },
+    ];
+  }
+  // Main branch build - check if there's a release version
+  if (releaseVersion !== 'unreleased') {
+    return [
+      { text: 'Development (main)', link: '/' },
+      { text: `Release (${releaseVersion})`, link: '/release/' },
+    ];
+  }
+  // No release yet
+  return [{ text: 'Development (main)', link: '/' }];
+}
+
 const guideSidebar = [
   {
     text: 'Getting Started',
@@ -73,6 +100,10 @@ export default defineConfig({
       { text: 'Guide', link: '/guide/' },
       { text: 'CLI Reference', link: '/cli/' },
       { text: 'API Reference', link: '/api/' },
+      {
+        text: isReleaseBuild ? releaseVersion : 'dev',
+        items: getVersionItems(),
+      },
     ],
 
     footer: {