Open source · vishwajit-vm Live
Strutvane Docs & Tooling
The live docs site and the CI that keeps 12 repos in sync
Two repositories that are already shipped: strutvane-docs, the friendly, example-first documentation site (live on GitHub Pages), and strutvane-tooling, which keeps the configs and CI/release workflows of all 12 Strutvane repositories identical — including token-free npm publishing.
Built for: Prospective users reading the docs, and maintainers of the Strutvane repositories.
↓ Scroll to explore the problem, architecture and stack
The problem
A polyrepo ecosystem drifts fast: every repo ends up with slightly different configs and workflows, and public docs start contradicting the design.
Why it matters
One source of truth for configs and workflows, synced safely into every repo, keeps the ecosystem consistent — and docs that are link-checked on every build stay trustworthy.
What you can do with it
How it’s built
A simplified view of the architecture — follow the dots as a request moves down the layers.
A request, step by step
- Docs are written as MDX; every push builds the site with Astro and runs both link checkers.
- A passing build deploys to GitHub Pages automatically.
- For configs, a maintainer edits a canonical file, previews with pnpm sync:dry, then syncs it into every repo.
- Each repo runs its own CI; sync:check fails if anything drifts from the canonical files.
- Releases publish to npm through trusted publishing, so no npm token is ever stored.
Tech stack
What I built
- Built the docs site with Astro and Starlight: 29 pages across getting started, concepts, packages, reference, a tutorial and community — deployed to GitHub Pages on every push to main.
- Added two link checkers (starlight-links-validator and a crawler over the built HTML) and a root-base build so a custom domain is ready.
- Built strutvane-tooling: canonical TypeScript, Biome and Vitest configs (coverage thresholds 90/90/85/90), CI and release workflows, Dependabot config and a sync script using only Node built-ins.
- Made sync safe: it validates the manifest first, rejects path traversal and unknown repos, normalises line endings to avoid false drift on Windows, and never deletes files.
- Set up token-free releases with npm trusted publishing (OIDC) and provenance; an idempotent publish step derives the dist-tag from the version (ADR-0016).
Hard problems & how I solved them
✅ Line endings are normalised to LF before comparing, so autocrlf no longer looks like a change.
✅ The manifest is validated first, unknown repos and path traversal are rejected, and the script never deletes.