chore: split docs by version

.github/copilot-instructions.md

@@ -29,7 +29,8 @@ Each package includes a DESIGN.md file, read that to gain a general understandin
 
 | Package | Status | Purpose |
 |---|---|---|
-| `sites/website` | Private (not published as a package) | Documentation website source |
+| `sites/website/docs` | Private (not published as a package) | Shared documentation website shell (`@microsoft/fast-site`) |
+| `sites/website/versions/{1x,2x,3x}` | Private (not published as packages) | Independently buildable version documentation source |
 | `sites/benchmarks` | Private (not published as a package) | Benchmarking site |
 
 ### Example projects

.github/skills/documentation/SKILL.md

@@ -9,7 +9,7 @@ Design/architectural documentation such as DESIGN.md should always be kept up-to
 
 The website captures the documentation primarily for the `@microsoft/fast-element` package. Other packages are treated as tangential, so testing packages or other utilities should have their own sections.
 
-The website has been written in 11ty and primarily consists of markdown files. When making changes, ensure that the website has been scanned on whichever latest major version is available. These are organized by folder, so if 1.x/2.x/3.x folders are available, you will update the documentation in the 3.x folder.
+The website has been written in 11ty and primarily consists of markdown files. When making changes, use the latest major version available. Version package directories omit the dot, so update `sites/website/versions/3x` for the public `/docs/3.x` content.
 
 If you are making a breaking change, ensure the migration document has been updated.
 

.github/skills/shipping/SKILL.md

@@ -205,12 +205,12 @@ If the breaking change is significant or requires multiple PRs, open a [discussi
 
 # Documentation
 
-After any changes ensure that the documentation is up to date, this includes the files DESIGN.md and README.md files for any packages/crates that have been modified. If your changes update or add to the public API, update the sites/website/src/docs/ files. Only update the latest version, these are denoted by major versions in their folder names inside the docs folder, 1.x, 2.x, etc., find the latest version of the docs and modify them if necessary.
+After any changes ensure that the documentation is up to date, this includes the files DESIGN.md and README.md files for any packages/crates that have been modified. If your changes update or add to the public API, update the latest version under `sites/website/versions/` (currently `sites/website/versions/3x/src`, published at `/docs/3.x`).
 
 When adding or modifying exported APIs, run the website prebuild script to regenerate API documentation from the api-extractor output:
 
 ```bash
-npm run prebuild -w sites/website
+npm run prebuild -w @microsoft/fast-site
 ```
 
-This runs [`sites/website/scripts/generate-docs.cjs`](../../../sites/website/scripts/generate-docs.cjs), which copies API documentation from each package's extracted API reports into the website source. Run this after building packages to ensure generated documentation stays in sync with the codebase.
+This runs [`sites/website/docs/scripts/generate-docs.cjs`](../../../sites/website/docs/scripts/generate-docs.cjs), which copies API documentation from each package's extracted API reports into the generated website staging tree. Run this after building packages to ensure generated documentation stays in sync with the codebase.

.github/workflows/cd-gh-pages.yml

@@ -2,16 +2,96 @@ name: Deploy GitHub Pages
 
 on:
   workflow_dispatch:
+  push:
+    branches:
+    - main
+    paths:
+    - .github/workflows/cd-gh-pages.yml
+    - lage.config.js
+    - package-lock.json
+    - package.json
+    - packages/fast-build/**
+    - packages/fast-element/**
+    - sites/website/docs/**
+    - sites/website/versions/**
 
-env:
-  GITHUB_SERVICE_USER: "Microsoft FAST Builds"
-  GITHUB_SERVICE_EMAIL: "fastsvc@microsoft.com"
+concurrency:
+  group: fast-documentation-pages
+  cancel-in-progress: false
 
 permissions:
   contents: write
 
 jobs:
-  build:
+  detect:
+    runs-on: ubuntu-latest
+    outputs:
+      full: ${{ steps.changes.outputs.full }}
+      has_changes: ${{ steps.changes.outputs.has_changes }}
+      versions: ${{ steps.changes.outputs.versions }}
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - id: changes
+      name: Select documentation builds
+      shell: bash
+      run: |
+        full=false
+        selected_1x=false
+        selected_2x=false
+        selected_3x=false
+
+        if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+          full=true
+        else
+          before="${{ github.event.before }}"
+
+          if [[ -z "$before" || "$before" =~ ^0+$ ]] || ! git cat-file -e "$before^{commit}"; then
+            full=true
+          else
+            mapfile -t changed_files < <(git diff --name-only "$before" "${{ github.sha }}")
+
+            for file in "${changed_files[@]}"; do
+              case "$file" in
+                .github/workflows/cd-gh-pages.yml|lage.config.js|package.json|package-lock.json|sites/website/docs/*)
+                  full=true
+                  ;;
+                packages/fast-build/*|packages/fast-element/*|sites/website/versions/3x/*)
+                  selected_3x=true
+                  ;;
+                sites/website/versions/1x/*)
+                  selected_1x=true
+                  ;;
+                sites/website/versions/2x/*)
+                  selected_2x=true
+                  ;;
+              esac
+            done
+          fi
+        fi
+
+        versions=()
+        if [[ "$full" != "true" ]]; then
+          [[ "$selected_1x" == "true" ]] && versions+=("1x")
+          [[ "$selected_2x" == "true" ]] && versions+=("2x")
+          [[ "$selected_3x" == "true" ]] && versions+=("3x")
+        fi
+
+        has_changes=false
+        if [[ "$full" == "true" || ${#versions[@]} -gt 0 ]]; then
+          has_changes=true
+        fi
+
+        echo "full=$full" >> "$GITHUB_OUTPUT"
+        echo "has_changes=$has_changes" >> "$GITHUB_OUTPUT"
+        echo "versions=${versions[*]}" >> "$GITHUB_OUTPUT"
+
+  deploy:
+    needs: detect
+    if: needs.detect.outputs.has_changes == 'true'
     runs-on: ubuntu-latest
 
     steps:
@@ -22,41 +102,80 @@ jobs:
     - uses: actions/setup-node@v6
       with:
         node-version: 22
+        cache: npm
 
-    - name: Set Git User
-      run: |
-        git config --global user.name "${{ env.GITHUB_SERVICE_USER }}"
-        git config --global user.email "${{ env.GITHUB_SERVICE_EMAIL }}"
+    - name: Install package dependencies
+      run: npm ci
+
+    - if: needs.detect.outputs.full == 'true' || contains(needs.detect.outputs.versions, '3x')
+      name: Install wasm-pack
+      run: cargo install wasm-pack
 
-    - name: Cache multiple paths
-      uses: actions/cache@v4
+    - name: Build documentation
       env:
-        cache-name: cache-node-modules
+        FULL_BUILD: ${{ needs.detect.outputs.full }}
+        VERSIONS: ${{ needs.detect.outputs.versions }}
+      shell: bash
+      run: |
+        if [[ "$FULL_BUILD" == "true" ]]; then
+          npx lage build --to @microsoft/fast-site --verbose
+        else
+          scopes=()
+          for version in $VERSIONS; do
+            scopes+=("@microsoft/fast-site-$version")
+          done
+          npx lage build --to "${scopes[@]}" --verbose
+        fi
+
+    - uses: actions/checkout@v4
       with:
-        path: ~/.npm
-        key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
-        restore-keys: |
-          ${{ runner.os }}-build-${{ env.cache-name }}-
-          ${{ runner.os }}-build-
-          ${{ runner.os }}-
+        fetch-depth: 1
+        path: .gh-pages
+        ref: gh-pages
 
-    - name: Install package dependencies
-      run: npm ci
+    - name: Update GitHub Pages content
+      env:
+        FULL_BUILD: ${{ needs.detect.outputs.full }}
+        VERSIONS: ${{ needs.detect.outputs.versions }}
+      shell: bash
+      run: |
+        if [[ "$FULL_BUILD" == "true" ]]; then
+          mkdir -p .gh-pages/docs
+          rsync -a --delete \
+            --exclude='.nojekyll' \
+            --exclude='CNAME' \
+            sites/website/docs/build/ .gh-pages/docs/
+        else
+          for version in $VERSIONS; do
+            public_version="${version%x}.x"
+            source="sites/website/versions/$version/build/docs/$public_version"
+            destination=".gh-pages/docs/docs/$public_version"
 
-    - name: Install wasm-pack
-      run: cargo install wasm-pack
+            mkdir -p "$destination"
+            rsync -a --delete "$source/" "$destination/"
+          done
+        fi
 
-    - name: Build workspaces
-      run: npm run build
+    - name: Commit GitHub Pages content
+      env:
+        FULL_BUILD: ${{ needs.detect.outputs.full }}
+        VERSIONS: ${{ needs.detect.outputs.versions }}
+      shell: bash
+      run: |
+        cd .gh-pages
+        git config user.name "Microsoft FAST Builds"
+        git config user.email "fastsvc@microsoft.com"
+        git add --all
 
-    - name: Build GitHub Pages
-      run: npm run build:gh-pages
+        if git diff --cached --quiet; then
+          echo "GitHub Pages content is already current."
+          exit 0
+        fi
 
-    - name: Deploy GitHub Pages
-      uses: JamesIves/github-pages-deploy-action@v4
-      with:
-        branch: gh-pages # The branch the action should deploy to.
-        folder: sites/website/build # The folder the action should deploy.
-        target-folder: docs # The folder on the branch to deploy to.
-        clean: true # Remove old files to clean up unique hash files.
-        single-commit: true # Only use a single commit to keep the branch free from git history.
+        target="$VERSIONS"
+        if [[ "$FULL_BUILD" == "true" ]]; then
+          target="full site"
+        fi
+
+        git commit -m "docs: deploy $target from $GITHUB_SHA"
+        git push origin HEAD:gh-pages

.gitignore

@@ -50,12 +50,11 @@ storybook-static
 .tmp/
 temp/
 
-# Docusaurus files to ignore
-sites/website/build/
-sites/website/docs/
-sites/website/src/docs/api/
-sites/website/node_modules
-sites/website/i18n/
+# Documentation website generated files
+sites/website/docs/build/
+sites/website/docs/tmp/
+sites/website/versions/*/build/
+sites/website/versions/*/tmp/
 
 # GitHub Actions Local Testing
 .github/workflows/testing/*.json

lage.config.js

@@ -5,6 +5,26 @@ module.exports = {
             dependsOn: ["^build"],
             outputs: ["dist/**", "wasm/**"],
         },
+        "@microsoft/fast-site#build": {
+            dependsOn: ["@microsoft/fast-build#build", "@microsoft/fast-element#build"],
+            cache: false,
+            outputs: ["build/**"],
+        },
+        "@microsoft/fast-site-1x#build": {
+            dependsOn: [],
+            cache: false,
+            outputs: ["build/**"],
+        },
+        "@microsoft/fast-site-2x#build": {
+            dependsOn: [],
+            cache: false,
+            outputs: ["build/**"],
+        },
+        "@microsoft/fast-site-3x#build": {
+            dependsOn: ["@microsoft/fast-element#build"],
+            cache: false,
+            outputs: ["build/**"],
+        },
         "@microsoft/fast-element#build": {
             dependsOn: ["@microsoft/fast-build#build"],
             outputs: ["dist/**"],
@@ -26,5 +46,7 @@ module.exports = {
         outputGlob: ["dist/**", "wasm/**"],
         environmentGlob: ["package.json", "tsconfig.json", "lage.config.js"],
     },
-    ignore: ["change/**", "*.md", ".github/**"],
+    // Ignore Markdown only at the repository root. Version package Markdown must
+    // remain visible to Lage's Micromatch-based affected package detection.
+    ignore: ["change/**", "[^/]*.md", ".github/**"],
 };

package.json

@@ -11,7 +11,11 @@
   "workspaces": [
     "build",
     "packages/*",
-    "sites/*",
+    "sites/benchmarks",
+    "sites/website/docs",
+    "sites/website/versions/1x",
+    "sites/website/versions/2x",
+    "sites/website/versions/3x",
     "examples/*",
     "examples/csr/*",
     "examples/ssr/*"