Set up deterministic GitBook-driven docs deployment

.github/workflows/docs-gitbook-sync.yml

@@ -0,0 +1,111 @@
+name: Docs GitBook Sync
+
+on:
+  schedule:
+    - cron: '7,37 * * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs-gitbook-sync
+  cancel-in-progress: true
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Read latest GitBook SHA
+        id: gitbook
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const { data } = await github.rest.repos.getCommit({
+              owner: 'stagecc',
+              repo: 'bdc-gitbook',
+              ref: 'main',
+            });
+            core.setOutput('sha', data.sha);
+
+      - name: Read current locked SHA
+        id: lock
+        run: |
+          node - <<'NODE'
+          const fs = require('node:fs');
+          const path = 'apps/docs/gitbook.lock.json';
+          let ref = '';
+
+          if (fs.existsSync(path)) {
+            try {
+              const parsed = JSON.parse(fs.readFileSync(path, 'utf8'));
+              if (parsed && typeof parsed.ref === 'string') ref = parsed.ref;
+            } catch {
+              ref = '';
+            }
+          }
+
+          fs.appendFileSync(process.env.GITHUB_OUTPUT, `ref=${ref}\n`);
+          NODE
+
+      - name: Update lock file
+        if: steps.gitbook.outputs.sha != steps.lock.outputs.ref
+        run: |
+          node - <<'NODE'
+          const fs = require('node:fs');
+          const path = 'apps/docs/gitbook.lock.json';
+          const sha = process.env.GITBOOK_SHA;
+
+          const lock = {
+            repo: 'https://github.com/stagecc/bdc-gitbook.git',
+            ref: sha,
+          };
+
+          fs.writeFileSync(path, `${JSON.stringify(lock, null, 2)}\n`);
+          NODE
+        env:
+          GITBOOK_SHA: ${{ steps.gitbook.outputs.sha }}
+
+      - name: Setup Node
+        if: steps.gitbook.outputs.sha != steps.lock.outputs.ref
+        uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+          cache: npm
+
+      - name: Install dependencies
+        if: steps.gitbook.outputs.sha != steps.lock.outputs.ref
+        run: npm ci
+
+      - name: Validate docs build
+        if: steps.gitbook.outputs.sha != steps.lock.outputs.ref
+        run: npm run build --workspace=@bdc/docs
+        env:
+          GITBOOK_REF: ${{ steps.gitbook.outputs.sha }}
+
+      - name: Commit updated lock
+        if: steps.gitbook.outputs.sha != steps.lock.outputs.ref
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git add "apps/docs/gitbook.lock.json"
+
+          if git diff --cached --quiet; then
+            echo "No lock changes to commit."
+            exit 0
+          fi
+
+          short_sha="${GITBOOK_SHA:0:12}"
+          git commit -m "chore(docs): sync GitBook lock to ${short_sha}"
+          git push
+        env:
+          GITBOOK_SHA: ${{ steps.gitbook.outputs.sha }}
+
+      - name: No content changes detected
+        if: steps.gitbook.outputs.sha == steps.lock.outputs.ref
+        run: echo "GitBook is already in sync at ${{ steps.lock.outputs.ref }}"

apps/docs/.gitignore

@@ -0,0 +1,5 @@
+# Build-time synced GitBook content
+src/content/docs/
+public/gitbook-assets/
+src/config/sidebar.generated.ts
+src/generated/gitbook-manifest.json

apps/docs/README.md

@@ -0,0 +1,71 @@
+# BDC Documentation App Overview
+
+This app (`@bdc/docs`) is an Astro + Starlight documentation site.
+
+Content is sourced from GitBook via the `stagecc/bdc-gitbook` repository, which is in-sync with the [BDC GitBook](https://bdcatalyst.gitbook.io/), and fetched at build time.
+
+## Source of truth
+
+- GitBook content repo: `https://github.com/stagecc/bdc-gitbook`
+- Lock file in this repo: `apps/docs/gitbook.lock.json`
+  - `repo`: Git URL to clone
+  - `ref`: pinned commit SHA to sync
+
+The lock file provides deterministic builds and deployment traceability.
+
+## How sync works
+
+Sync is handled by `apps/docs/scripts/sync-gitbook.mjs`.
+
+At a high level, the script:
+
+1. resolves source repo/ref from env vars, then lock file;
+2. clones GitBook content into a temporary directory;
+3. rebuilds generated docs content and assets from scratch;
+4. converts GitBook markdown syntax into Starlight-compatible markdown;
+5. generates sidebar config from `SUMMARY.md`; and
+6. writes a sync manifest (source repo/ref/sha and counts).
+
+Generated outputs (ignored by git):
+
+- `apps/docs/src/content/docs/`
+- `apps/docs/public/gitbook-assets/`
+- `apps/docs/src/config/sidebar.generated.ts`
+- `apps/docs/src/generated/gitbook-manifest.json`
+
+## Local commands
+
+From repo root:
+
+- Build docs (sync first):
+  - `npm run build --workspace=@bdc/docs`
+- Dev server only (fast loop, no sync):
+  - `npm run dev --workspace=@bdc/docs`
+- Sync then run dev server:
+  - `npm run dev:sync --workspace=@bdc/docs`
+- Sync content only (supporting local dev):
+  - `npm run sync:content --workspace=@bdc/docs`
+
+Notes:
+
+- The sync script requires `GITBOOK_ALLOW_OVERWRITE=1` to prevent accidental destructive writes.
+- Package scripts set this automatically for normal usage.
+
+## CI / deployment flow
+
+Workflow: `.github/workflows/docs-gitbook-sync.yml`
+
+- Runs on schedule and manual dispatch
+- Checks latest `stagecc/bdc-gitbook` `main` commit
+- Compares to `apps/docs/gitbook.lock.json`
+- If changed:
+  - updates lock file
+  - validates docs build
+  - commits lock update
+
+Amplify listens to this repository and deploys `apps/docs` from resulting commits.
+
+## Operational guidance
+
+- To pin docs to a specific GitBook commit manually, update `apps/docs/gitbook.lock.json` and commit.
+- To test against a different ref temporarily, set `GITBOOK_REF` when running `sync-gitbook.mjs`.

apps/docs/astro.config.mjs

@@ -2,7 +2,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import starlight from '@astrojs/starlight';
 import { defineConfig } from 'astro/config';
-import { sidebar } from './src/config/sidebar.ts';
+import { sidebar } from './src/config/sidebar.generated.ts';
 
 const rootDir = dirname(fileURLToPath(import.meta.url));
 const uswdsPackages = join(rootDir, '../../node_modules/@uswds/uswds/packages');
@@ -26,6 +26,7 @@ export default defineConfig({
         },
       ],
       customCss: ['./src/styles/custom.scss'],
+      disable404Route: true,
       sidebar,
     }),
   ],

apps/docs/gitbook.lock.json

@@ -0,0 +1,4 @@
+{
+  "repo": "https://github.com/stagecc/bdc-gitbook.git",
+  "ref": "e9780d21ef367b15d45bf45ad1a1c24f9e007f83"
+}

apps/docs/package.json

@@ -5,7 +5,9 @@
   "type": "module",
   "scripts": {
     "dev": "astro dev",
-    "build": "astro build",
+    "dev:sync": "npm run sync:content && astro dev",
+    "sync:content": "GITBOOK_ALLOW_OVERWRITE=1 node ./scripts/sync-gitbook.mjs",
+    "build": "npm run sync:content && astro build",
     "preview": "astro preview"
   },
   "dependencies": {