feat: publish the theme's documentation as a developer spoke

.github/workflows/ci.yml

@@ -0,0 +1,103 @@
+# Build both halves of the repository on every pull request and on main.
+#
+# The two jobs are separate because they install differently and fail for
+# different reasons: the package builds under yarn from the root lockfile, the
+# documentation site builds under npm from its own. Splitting them means a
+# broken docs build never hides a broken package build.
+
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  package:
+    name: build package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+          cache: yarn
+          cache-dependency-path: yarn.lock
+
+      - name: Enable corepack
+        run: corepack enable
+
+      - run: yarn install --frozen-lockfile
+
+      - run: yarn build
+
+      # `files` in package.json decides what reaches consumers, and it is the
+      # one thing a successful `tsc` says nothing about. Pack the tarball and
+      # assert the assets the design system references are inside it, so a file
+      # added outside lib/, src/ or static/ fails here rather than in a
+      # consumer's site.
+      - name: Verify the tarball ships its assets
+        run: |
+          set -euo pipefail
+          contents=$(npm pack --dry-run --json | tr -d ' ')
+          missing=0
+          for asset in \
+            lib/index.cjs \
+            lib/index.d.cts \
+            src/css/custom.css \
+            src/utils/rehypeTabsTransform.js \
+            static/fonts/Satoshi-Regular.woff \
+            static/img/vantage-logo-color.svg \
+            static/img/favicon.ico
+          do
+            if ! grep -q "\"$asset\"" <<<"$contents"; then
+              echo "not in the tarball: $asset"
+              missing=1
+            fi
+          done
+
+          if [ "$missing" -ne 0 ]; then
+            echo "Likely cause: a file was added outside the directories listed"
+            echo "in \`files\` in package.json."
+            exit 1
+          fi
+
+          echo "Tarball contents OK"
+
+  docs:
+    name: build docs
+    runs-on: ubuntu-latest
+    steps:
+      # fetch-depth: 0 for the same reason the deploy workflow needs it: the
+      # version badge comes from `git describe --tags`.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: docusaurus/package-lock.json
+
+      - name: Install docs dependencies
+        working-directory: docusaurus
+        run: npm ci
+
+      - name: Typecheck
+        working-directory: docusaurus
+        run: npm run typecheck
+
+      # `onBrokenLinks: 'throw'` means this also checks every internal link on
+      # the site.
+      - name: Build docs
+        working-directory: docusaurus
+        run: npm run build

.github/workflows/deploy-docs.yml

@@ -0,0 +1,136 @@
+# Deploy this package's documentation as a spoke site under
+# /developer/docusaurus-theme/ on docs.vantagecompute.ai (S3 + CloudFront).
+#
+# Auth is handled at the edge by the Lambda@Edge Keycloak gateway on all of
+# /developer/*, so there is no per-spoke auth configuration here and the site
+# carries no login of its own.
+#
+# Required repo variables:
+#   DOCS_BUCKET               S3 bucket name (shared with vantage-docs)
+#   DOCS_CF_DISTRIBUTION_ID   CloudFront distribution ID
+#
+# Required repo secrets:
+#   DOCS_SPOKE_ROLE_ARN       vantage-docs-spoke-docusaurus-theme, scoped to
+#                             developer/docusaurus-theme/*. Created by the
+#                             vantage-docs hub stack from its own spokes list,
+#                             so there is no infrastructure to deploy from here
+#                             -- adding this repo to that list is what brings
+#                             the role into existence.
+
+name: Deploy docs (spoke)
+
+on:
+  # The docs live in this repository and are not generated from a release
+  # artifact, so main is the source of truth for them: a wording fix should not
+  # have to wait for the next version bump. The tag trigger is still here
+  # because `getProjectVersion()` reads `git describe`, so a release changes
+  # what the navbar badge says even when no page did.
+  push:
+    branches: [main]
+    paths:
+      - 'docusaurus/**'
+      - '.github/workflows/deploy-docs.yml'
+    tags:
+      # Only a plain vX.Y.Z release republishes. `v*` also matched a
+      # pre-release like v1.2.3rc1 and anything else beginning with v. GitHub
+      # filter patterns are glob-like rather than regular expressions: `.` is
+      # literal and `+` means one or more of the preceding character, so this
+      # matches v1.2.3 and v10.20.30 and rejects v1.2.3rc1, v1.2 and vfoo.
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: read
+
+concurrency:
+  group: docs-spoke
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      # fetch-depth: 0 rather than the default 1. The site's version badge comes
+      # from `getProjectVersion()`, which shells out to `git describe --tags`;
+      # a shallow checkout carries no tags, so the badge would read as a bare
+      # commit hash on every deploy.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: docusaurus/package-lock.json
+
+      - name: Install docs dependencies
+        working-directory: docusaurus
+        run: npm ci
+
+      - name: Typecheck
+        working-directory: docusaurus
+        run: npm run typecheck
+
+      - name: Build docs
+        working-directory: docusaurus
+        run: npm run build
+
+      # The site installs @vantagecompute/docusaurus-theme from npm rather than
+      # from the working tree, so the build above already proves the published
+      # tarball is usable. What it does not prove is that the tarball still
+      # ships static/: a missing asset directory produces a site that builds
+      # clean and renders in the wrong typeface. Check for the assets the design
+      # system references rather than trusting the exit code.
+      - name: Verify the published package still ships its assets
+        working-directory: docusaurus
+        run: |
+          set -euo pipefail
+          pkg=node_modules/@vantagecompute/docusaurus-theme
+          missing=0
+          for asset in \
+            static/fonts/Satoshi-Regular.woff \
+            static/img/vantage-logo-color.svg \
+            static/img/favicon.ico \
+            src/css/custom.css \
+            lib/index.cjs
+          do
+            if [ ! -f "$pkg/$asset" ]; then
+              echo "missing from the published package: $asset"
+              missing=1
+            fi
+          done
+
+          if [ "$missing" -ne 0 ]; then
+            echo "Likely cause: a file was added outside the directories listed"
+            echo "in \`files\` in package.json, so it never reached the tarball."
+            exit 1
+          fi
+
+          echo "Published package assets OK"
+
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@cbe3b392738ccf3f987d68400dafcf4b0624a56c # v6.2.4
+        with:
+          role-to-assume: ${{ secrets.DOCS_SPOKE_ROLE_ARN }}
+          aws-region: us-east-1
+
+      # --delete is safe here and only here: the hub excludes every spoke listed
+      # in .developer-subsites from its own sync, so this subtree is owned by
+      # this repo alone.
+      - name: Sync to S3
+        run: |
+          aws s3 sync docusaurus/build/ "s3://${{ vars.DOCS_BUCKET }}/developer/docusaurus-theme/" --delete
+
+      - name: Invalidate CloudFront
+        env:
+          DOCS_CF_DISTRIBUTION_ID: ${{ vars.DOCS_CF_DISTRIBUTION_ID }}
+        run: |
+          if [ -z "${DOCS_CF_DISTRIBUTION_ID}" ]; then
+            echo "DOCS_CF_DISTRIBUTION_ID is not set; skipping CloudFront invalidation."
+            exit 0
+          fi
+          aws cloudfront create-invalidation \
+            --distribution-id "${DOCS_CF_DISTRIBUTION_ID}" \
+            --paths "/developer/docusaurus-theme/*"

.github/workflows/publish.yml

@@ -12,9 +12,9 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: 24
           registry-url: https://registry.npmjs.org

.gitignore

@@ -1,3 +1,7 @@
 node_modules/
 lib/
 *.tgz
+
+# Docs site
+docusaurus/.docusaurus/
+docusaurus/build/

MIGRATION.md

@@ -5,9 +5,9 @@ Two migrations live here:
 - **[Part 1: adopting the theme](#part-1-adopting-the-theme)** walks the
   `vantage-docs` project through its first move onto the shared package. Any
   site not yet on the theme follows the same steps.
-- **[Part 2: adopting the shared brand mark](#part-2-adopting-the-shared-brand-mark-050)**
+- **[Part 2: adopting the shared brand mark](#part-2-adopting-the-shared-brand-mark-047)**
   is for a site already on the theme that still carries its own copy of the
-  logo and its own navbar/footer logo config. Added in 0.5.0.
+  logo and its own navbar/footer logo config. Added in 0.4.7.
 
 ## Part 1: adopting the theme
 
@@ -142,7 +142,7 @@ Check that:
 
 ---
 
-## Part 2: adopting the shared brand mark (0.5.0)
+## Part 2: adopting the shared brand mark (0.4.7)
 
 For a site already using the theme that has its own
 `static/img/vantage-logo-color.svg` and hand-written navbar and footer logo
@@ -151,7 +151,7 @@ blocks. After this, the mark and its wiring come from the package.
 ### Step 1: Upgrade the package
 
 ```bash
-npm install @vantagecompute/docusaurus-theme@^0.5.0
+npm install @vantagecompute/docusaurus-theme@0.4.7
 ```
 
 ### Step 2: Delete your copy of the brand mark

README.md

@@ -91,8 +91,8 @@ Served from the package once `staticDir` is in your `staticDirectories`, so no s
 |---|---|
 | `ColorModeToggle` | Custom sun/moon SVG icon toggle |
 | `DocBreadcrumbs` | Full-path breadcrumb rendering |
+| `Navbar/Logo` | Centered site title with the version badge beside it |
 | `Tabs` | Bugfix for Docusaurus 3.10 whitespace crash |
-| `MDXComponents` | Global `Tabs`/`TabItem` registration |
 | `Navbar/MobileSidebar/SecondaryMenu` | Clean secondary menu render |
 
 ### Utilities
@@ -154,6 +154,22 @@ Override any design token in your custom CSS:
 }
 ```
 
+## Documentation
+
+Full documentation is published as a spoke site on the Vantage docs hub:
+
+**https://docs.vantagecompute.ai/developer/docusaurus-theme/**
+
+It lives in `docusaurus/` in this repository and installs the theme from npm at
+a pinned version, so it renders what consumers actually get rather than the
+working tree.
+
+```bash
+just docs-serve         # local preview at /developer/docusaurus-theme/
+just docs-build         # build and link-check
+just docs-pin 0.4.8     # point the site at a newly published version
+```
+
 ## Development
 
 ```bash
@@ -163,6 +179,16 @@ npm run build    # Compile TypeScript entry point
 
 The package uses TypeScript for the plugin entry point (`src/index.cts` -> `lib/index.cjs`). Theme components, CSS, and static assets are shipped as source and resolved by Docusaurus at build time.
 
+`tsconfig.json` deliberately excludes `src/theme`, `src/css` and `src/utils`: only the entry point is compiled here, and everything else is compiled by each consuming site's own toolchain.
+
+## Releasing
+
+```bash
+just release 0.4.8
+```
+
+Bumps `package.json`, commits, tags, pushes, and creates the GitHub release. The npm publish runs in CI on `release: published`, with provenance attestation. Afterwards, bump the docs site's pin with `just docs-pin`.
+
 ## License
 
 MIT

docusaurus/.gitignore

@@ -0,0 +1,12 @@
+# Docusaurus
+.docusaurus/
+build/
+.cache-loader/
+
+# Dependencies
+node_modules/
+
+# Misc
+.DS_Store
+*.log
+npm-debug.log*