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

[jamesbeedy]

The theme now carries the shared brand mark and the navbar and footer logo definitions, so it has documentation worth publishing rather than only being a dependency of the sites that do. This adds that site, in docusaurus/, and deploys it under docs.vantagecompute.ai/developer/docusaurus-theme/ alongside every other spoke.

Companion: vantagecompute/vantage-docs#120 registers the spoke and mints the deploy role. That has to land and deploy first or the deploy workflow here fails at the credentials step.

The site

12 pages in docusaurus/docs/: overview, installation, usage, migration, contributing, a design-system section (tokens, typography) and a reference section (exports, components, assets, customization).

Spoke contract settings: baseUrl: '/developer/docusaurus-theme/', trailingSlash: false (the edge rewrites extensionless URLs to {path}.html), noIndex: true.

It installs the published tarball, not the working tree

package.json pins "@vantagecompute/docusaurus-theme": "0.4.7" from npm rather than a file: link to the repository around it. A file: link would render the working tree, so the site would show a design nobody can install yet, and it would never catch a packaging mistake: a file the build needs that files in package.json does not ship.

The cost is that the pin trails the package by up to one release. just docs-pin <version> moves it, and refuses a version that is not on npm yet.

Workflows

File	Trigger
ci.yml (new)	PR and main. One job builds the package under yarn; one typechecks and builds the docs
deploy-docs.yml (new)	push to main touching docusaurus/**, a v[0-9]+.[0-9]+.[0-9]+ tag, or dispatch
publish.yml	unchanged behaviour, actions repinned

Two details worth review:

Both jobs assert the asset list rather than trusting a green build. A site missing static/ builds clean and renders in the wrong typeface, so neither exit code tells you anything. CI checks npm pack --dry-run --json; the deploy checks what npm actually installed into node_modules.

Both checkouts use fetch-depth: 0. getProjectVersion() shells out to git describe --tags, and a shallow checkout carries no tags, so the navbar badge would read as a bare commit hash on every deploy. (Worth porting to the other spokes; armasec-lite has this bug.)

The docs deploy triggers on main rather than only on a tag because the pages live in this repository and are not generated from a release artifact: a wording fix should not wait for the next version bump. The tag trigger stays because a release changes what the version badge says even when no page did.

TypeScript 7

Two accommodations in the docs site:

• @docusaurus/tsconfig still sets baseUrl, which TS7 removed, so extending it fails before it compiles anything. The options are inlined instead.
• staticDirectories lists only the theme's directory. Git does not track empty directories, so a local static/ with nothing in it fails the client bundle outright with unable to locate ... glob.

Alongside

• Every action pinned to the SHA of its latest release, publish.yml included, which was on floating @v4 tags. Verified against releases/latest: checkout v7.0.1, setup-node v7.0.0, configure-aws-credentials v6.2.4. All jobs on node 24.
• Dev dependencies bumped to current releases (docusaurus 3.10.2, @types/node 26.4.1, @types/react 19.2.18). npm-check-updates is clean in both package.json files.
• README component table fixed: it listed an MDXComponents override that does not exist in src/theme/, and omitted the Navbar/Logo one that does.
• MIGRATION.md dated the shared brand mark to an unreleased 0.5.0. It shipped in 0.4.7.
• justfile gains docs-install, docs-serve, docs-build, docs-clean, docs-pin.

Verification

npm run typecheck and npm run build both pass from a clean tree. onBrokenLinks: 'throw', so the build link-checks the site. The rendered build/index.html carries v0.4.7 in the version badge, and the fonts, icons and favicon all resolve out of the package.

Before this can deploy

After vantagecompute/vantage-docs#120 lands and the stack deploys, set on this repo:

• vars DOCS_BUCKET, DOCS_CF_DISTRIBUTION_ID
• secret DOCS_SPOKE_ROLE_ARN (vantage-docs-spoke-docusaurus-theme)

ci.yml needs none of them.

🤖 Generated with Claude Code