← Back to all projects
📖

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.

29 docs pages2 link checkers3 OS × 2 Node versions

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

01Read getting-started guides, concepts, package pages, reference and a “build a CRM in 2 hours” tutorial.
02Trust every link: two link checkers run on each build.
03Sync canonical configs into all repos with a dry run first; drift fails CI.
04Publish releases without long-lived npm tokens, using trusted publishing with provenance.

How it’s built

A simplified view of the architecture — follow the dots as a request moves down the layers.

Sources
MDX pagesstrutvane-docs
canonical/ configsstrutvane-tooling
Build & check
Astro build
Link checkers2 independent
sync:checkfails on drift
Delivery
GitHub Pageslive docs
12 repositoriesidentical CI
npmOIDC trusted publishing

A request, step by step

  1. Docs are written as MDX; every push builds the site with Astro and runs both link checkers.
  2. A passing build deploys to GitHub Pages automatically.
  3. For configs, a maintainer edits a canonical file, previews with pnpm sync:dry, then syncs it into every repo.
  4. Each repo runs its own CI; sync:check fails if anything drifts from the canonical files.
  5. Releases publish to npm through trusted publishing, so no npm token is ever stored.

Tech stack

Docs
AstroStarlightMDX
Tooling
GitHub ActionsBiomeVitestNode.js
Release
npm trusted publishingChangesets

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

❓ False drift on Windows.

✅ Line endings are normalised to LF before comparing, so autocrlf no longer looks like a change.

❓ A broken manifest could half-sync the ecosystem.

✅ The manifest is validated first, unknown repos and path traversal are rejected, and the script never deletes.