feat: versioned release docs deployment

.github/workflows/docs.yml

@@ -3,12 +3,7 @@ name: Documentation
 on:
   push:
     branches:
-      - main
-    paths:
-      - 'docs/**'
-      - 'docs-site/**'
-      - 'scripts/prepare-docs.sh'
-      - '.github/workflows/docs.yml'
+      - 'v*-docs'
   pull_request:
     paths:
       - 'docs/**'
@@ -59,9 +54,9 @@ jobs:
         with:
           path: ./docs-site/dist
 
-  # Deployment job - only runs on main branch
+  # Deployment job - only runs on the active docs branch
   deploy:
-    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == format('refs/heads/{0}', vars.ACTIVE_DOCS_BRANCH)
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

.github/workflows/release-docs-branch.yml

@@ -0,0 +1,68 @@
+name: Release Docs Branch
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version tag to create docs branch from (e.g., v0.1.0, v0.1.0-beta.5)'
+        required: true
+        type: string
+      branch_strategy:
+        description: 'Branch naming strategy'
+        required: false
+        type: choice
+        options:
+          - major-minor
+          - full-version
+        default: major-minor
+
+jobs:
+  create-docs-branch:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.version }}
+          fetch-depth: 0
+
+      - name: Create docs branch
+        env:
+          TAG_NAME: ${{ inputs.version }}
+          BRANCH_STRATEGY: ${{ inputs.branch_strategy }}
+        run: |
+          # Extract version from tag (remove 'v' prefix if present)
+          VERSION="${TAG_NAME#v}"
+
+          # Determine branch name based on strategy
+          if [[ "$BRANCH_STRATEGY" == "major-minor" ]]; then
+            # Extract major.minor (e.g., "0.1.0" -> "0.1", "0.1.0-beta.5" -> "0.1")
+            MAJOR_MINOR=$(echo "$VERSION" | cut -d. -f1,2)
+            BRANCH_NAME="v${MAJOR_MINOR}-docs"
+          else
+            # Use full version
+            BRANCH_NAME="${TAG_NAME}-docs"
+          fi
+
+          echo "Creating docs branch: $BRANCH_NAME from tag $TAG_NAME"
+
+          # Check if branch already exists
+          if git ls-remote --exit-code --heads origin "$BRANCH_NAME" > /dev/null 2>&1; then
+            echo "⚠️  Branch $BRANCH_NAME already exists"
+            echo "If you want to update it, delete the branch first and re-run this workflow"
+            exit 1
+          fi
+
+          # Configure git
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          # Create and push the branch
+          git checkout -b "$BRANCH_NAME"
+          git push origin "$BRANCH_NAME"
+
+          echo "✅ Successfully created branch $BRANCH_NAME"
+          echo "Next steps:"
+          echo "1. Set ACTIVE_DOCS_BRANCH variable to: $BRANCH_NAME"
+          echo "2. Trigger the docs workflow to deploy"

docs-site/astro.config.mjs

@@ -17,6 +17,9 @@ export default defineConfig({
       title: 'ICP CLI',
       description: 'Command-line tool for developing and deploying applications on the Internet Computer Protocol (ICP)',
       favicon: '/favicon.png',
+      components: {
+        SiteTitle: './src/components/SiteTitle.astro',
+      },
       head: [
         {
           tag: 'script',

docs-site/src/components/SiteTitle.astro

@@ -0,0 +1,50 @@
+---
+import type { Props } from '@astrojs/starlight/props';
+import config from 'virtual:starlight/user-config';
+import VersionBadge from './VersionBadge.astro';
+
+const { hasSiteTitleLogo } = Astro.props;
+// Ensure title is a string
+const titleText = typeof config.title === 'string' ? config.title : 'ICP CLI';
+---
+
+<a href={import.meta.env.BASE_URL} class="site-title sl-flex">
+	{
+		config.logo && hasSiteTitleLogo && 'src' in config.logo ? (
+			<img
+				class:list={{ 'light:sl-hidden': config.logo.dark }}
+				alt={config.logo.alt}
+				src={config.logo.src}
+				width={config.logo.width}
+				height={config.logo.height}
+			/>
+		) : null
+	}
+	{
+		config.logo?.dark && hasSiteTitleLogo && 'src' in config.logo.dark ? (
+			<img
+				class="dark:sl-hidden"
+				alt={config.logo.dark.alt || config.logo?.alt}
+				src={config.logo.dark.src}
+				width={config.logo.dark.width ?? config.logo?.width}
+				height={config.logo.dark.height ?? config.logo?.height}
+			/>
+		) : null
+	}
+	<span class:list={{ 'sr-only': hasSiteTitleLogo && config.logo?.replacesTitle }}>
+		{titleText}
+	</span>
+	<VersionBadge />
+</a>
+
+<style>
+	.site-title {
+		align-items: center;
+		gap: var(--sl-nav-gap);
+		font-size: var(--sl-text-h4);
+		font-weight: 600;
+		color: var(--sl-color-text-accent);
+		text-decoration: none;
+		white-space: nowrap;
+	}
+</style>

docs-site/src/components/VersionBadge.astro

@@ -0,0 +1,59 @@
+---
+// Read version from Cargo.toml at build time
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+
+let version = 'unknown';
+try {
+  const cargoToml = readFileSync(resolve('../Cargo.toml'), 'utf-8');
+  // Match version in [workspace.package] section or at root level
+  const versionMatch = cargoToml.match(/\[workspace\.package\][^\[]*version\s*=\s*"([^"]+)"/s)
+    || cargoToml.match(/^version\s*=\s*"([^"]+)"/m);
+  if (versionMatch) {
+    version = versionMatch[1];
+  }
+} catch (error) {
+  console.error('Failed to read version from Cargo.toml:', error);
+}
+---
+
+<div class="version-badge">
+  <span class="version-label">v{version}</span>
+</div>
+
+<style>
+  .version-badge {
+    display: inline-flex;
+    align-items: center;
+    margin-left: 0.75rem;
+  }
+
+  .version-label {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    padding: 0.25rem 0.625rem;
+    background: var(--sl-color-gray-6);
+    color: var(--sl-color-white);
+    border-radius: 0.375rem;
+    border: 1px solid var(--sl-color-gray-5);
+    white-space: nowrap;
+  }
+
+  /* Better contrast in light mode */
+  :root[data-theme='light'] .version-label {
+    background: var(--sl-color-gray-5);
+    color: var(--sl-color-white);
+    border-color: var(--sl-color-gray-4);
+  }
+
+  @media (max-width: 50rem) {
+    .version-badge {
+      margin-left: 0.5rem;
+    }
+
+    .version-label {
+      font-size: 0.75rem;
+      padding: 0.1875rem 0.5rem;
+    }
+  }
+</style>

scripts/prepare-docs.sh

@@ -109,9 +109,9 @@ find "$TARGET_DIR" -name "*.md" -type f | while read -r file; do
   {
     echo "---"
     echo "title: $title"
-    # Add banner to all pages (will be removed once versioning is introduced)
+    # Banner encouraging user feedback
     echo "banner:"
-    echo "  content: 'This documentation reflects the latest main branch and may include features not yet in the <a href=\"https://github.com/dfinity/icp-cli/releases\" target=\"_blank\" rel=\"noopener noreferrer\">current beta release</a>. Feedback welcome on the <a href=\"https://forum.dfinity.org/t/first-beta-release-of-icp-cli/60410\" target=\"_blank\" rel=\"noopener noreferrer\">Forum</a> or <a href=\"https://discord.internetcomputer.org\" target=\"_blank\" rel=\"noopener noreferrer\">Discord</a>!'"
+    echo "  content: 'Feedback welcome! Report issues on <a href=\"https://github.com/dfinity/icp-cli/issues\" target=\"_blank\" rel=\"noopener noreferrer\">GitHub</a>, ask questions on the <a href=\"https://forum.dfinity.org/t/icp-cli-announcements-and-feedback-discussion/60410/1\" target=\"_blank\" rel=\"noopener noreferrer\">Forum</a>, or chat with us on <a href=\"https://discord.internetcomputer.org\" target=\"_blank\" rel=\"noopener noreferrer\">Discord</a>.'"
     echo "---"
     echo ""
     # Remove the first H1 heading line from content to avoid duplicates