Fixing versioned documentation support

Author: TonsOfFun

.github/workflows/docs.yml

@@ -31,6 +31,11 @@ jobs:
           node-version: 22
           cache: npm
 
+      - name: Install system deps
+        run: |
+          sudo apt-get update
+          sudo apt-get install --no-install-recommends -y build-essential git libyaml-dev pkg-config
+
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
@@ -40,9 +45,6 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Install Ruby dependencies
-        run: bundle install
-
       - name: Generate versions.json
         run: |
           CURRENT_VERSION=$(grep 'VERSION = "' lib/active_agent/version.rb | sed 's/.*VERSION = "\([^"]*\)".*/\1/')
@@ -51,21 +53,23 @@ jobs:
             "current": "$CURRENT_VERSION",
             "versions": [
               { "version": "$CURRENT_VERSION", "label": "$CURRENT_VERSION (Latest)", "path": "/" },
-              { "version": "1.0.0", "label": "1.0.0", "path": "/v1.0.0/" },
-              { "version": "0.6.3", "label": "0.6.3", "path": "/v0.6.3/" }
+              { "version": "0.6.3", "label": "0.6.3", "path": "/v0.6.3/docs" }
             ]
           }
           EOF
 
+      - name: Install dummy app dependencies
+        working-directory: test/dummy
+        run: bundle install
+
       - name: Setup database
         env:
           RAILS_ENV: test
           RAILS_MASTER_KEY: ${{ secrets.RAILS_MASTER_KEY }}
+        working-directory: test/dummy
         run: |
-          cd test/dummy
           bundle exec rails db:create
           bundle exec rails db:migrate
-          cd ../..
 
       - name: Generate doc examples from tests
         env:
@@ -86,16 +90,13 @@ jobs:
           path: docs/.vitepress/dist
 
   # Build versioned docs using matrix strategy
+  # Note: Versioned docs are built from static content in tags (no test generation needed)
   build-versioned:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        include:
-          - version: "1.0.0"
-            ruby: "3.4"
-          - version: "0.6.3"
-            ruby: "3.3"
+        version: ["0.6.3"]
     steps:
       - name: Checkout version ${{ matrix.version }}
         uses: actions/checkout@v6
@@ -109,50 +110,31 @@ jobs:
           node-version: 22
           cache: npm
 
-      - name: Setup Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: ${{ matrix.ruby }}
-          bundler-cache: true
-
       - name: Install dependencies
         run: npm ci
 
-      - name: Install Ruby dependencies
-        run: bundle install
-
-      - name: Setup database
-        env:
-          RAILS_ENV: test
-          RAILS_MASTER_KEY: ${{ secrets.RAILS_MASTER_KEY }}
+      - name: Inject base path into existing config
         run: |
-          cd test/dummy
-          bundle exec rails db:create || true
-          bundle exec rails db:migrate || true
-          cd ../..
+          # Insert base path after the first defineConfig({ line
+          # This preserves the original sidebar, nav, and all other settings
+          sed -i "s|export default defineConfig({|export default defineConfig({\n  base: '/v${{ matrix.version }}/',\n  ignoreDeadLinks: true,|" docs/.vitepress/config.mts
 
-      - name: Generate doc examples from tests
-        env:
-          RAILS_ENV: test
-          RAILS_MASTER_KEY: ${{ secrets.RAILS_MASTER_KEY }}
-          ANTHROPIC_API_KEY: ANTHROPIC_API_KEY
-          OPEN_AI_API_KEY: OPEN_AI_API_KEY
-          OPEN_ROUTER_API_KEY: OPEN_ROUTER_API_KEY
-        run: bin/test || echo "Tests completed"
-
-      - name: Create versioned config
-        run: |
-          cat > docs/.vitepress/config.versioned.mts << EOF
-          import baseConfig from './config.mts'
-
-          export default {
-            ...baseConfig,
-            base: '/v${{ matrix.version }}/'
-          }
-          EOF
+          # Show the modified config for debugging
+          echo "Modified config.mts:"
+          head -20 docs/.vitepress/config.mts
 
       - name: Build VitePress docs for v${{ matrix.version }}
-        run: npx vitepress build docs --config docs/.vitepress/config.versioned.mts
+        run: npx vitepress build docs
+
+      - name: Fix internal links for versioned docs
+        run: |
+          # Rewrite internal absolute links to include the version prefix
+          # This fixes links in markdown content that use absolute paths like /docs/...
+          find docs/.vitepress/dist -name "*.html" -exec sed -i \
+            -e 's|href="/docs/|href="/v${{ matrix.version }}/docs/|g' \
+            -e 's|href="/activeagent.png"|href="/v${{ matrix.version }}/activeagent.png"|g' \
+            {} \;
+          echo "Fixed internal links for v${{ matrix.version }}"
 
       - name: Upload versioned docs artifact
         uses: actions/upload-artifact@v5

docs/.vitepress/config.mts

@@ -9,10 +9,13 @@ import {
 
 import versions from './versions.json'
 
-// Build version dropdown items
+// Build version dropdown items with absolute URLs for cross-version navigation
+// This forces full page reload instead of client-side routing
 const versionItems = versions.versions.map(v => ({
   text: v.label,
-  link: v.path
+  link: v.path.startsWith('/v')
+    ? `https://docs.activeagents.ai${v.path}`
+    : v.path
 }))
 
 // Support versioned builds via VITEPRESS_BASE env var

docs/.vitepress/versions.json

@@ -9,8 +9,8 @@
     },
     {
       "version": "0.6.3",
-      "label": "0.6.3 (Stable)",
-      "path": "/v0.6.3/",
+      "label": "0.6.3",
+      "path": "/v0.6.3/docs",
       "tag": "v0.6.3"
     }
   ]