OrbitalReg documentation site

VitePress source for docs.orbitalreg.com.

The canonical Markdown trees in ../docs/ remain the engineering source of truth — readable on GitHub without VitePress rendering. The pages here are the public-facing distillation: landing, guides, format references, operator + Terraform reference, operations runbooks.

Local development

cd docs-site
npm install
npm run dev

Defaults to http://localhost:5173. Hot-reload picks up Markdown edits and config changes.

Build

npm run build       # → .vitepress/dist/
npm run preview     # serve the built site locally

For a path-prefixed deploy (e.g. /docs/):

DOCS_BASE_PATH=/docs/ npm run build

Deploy

CI builds + deploys this site on every push to main via .github/workflows/docs.yml:

• Push to main → rsync to the IONOS Frankfurt VM that already serves orbitalreg.com / portal.orbitalreg.com, then smoke-test through the basic-auth pre-launch gate
• Pull request → build only; the uploaded docs-site-<sha> artefact is downloadable from the Actions run for local inspection
• Tag v* → tag-driven release rebuilds live in their own workflow (versioned /v<tag>/ subroute)

Adding pages

1. Drop a .md file under the appropriate section folder (guide/, formats/, operations/, operator/, reference/)
2. Add a sidebar entry in .vitepress/config.ts
3. Cross-link from the section's index.md so it's discoverable
4. Run npm run build locally — ignoreDeadLinks is on, so a broken link fails the build

Air-gapped tarball

npm ci
DOCS_BASE_PATH=/docs/ npm run build
tar czf orbitalreg-docs-${VERSION}.tar.gz -C .vitepress/dist .

The tarball is fully self-contained — no external CSS, JS, fonts, or search calls at runtime. Untar behind any reverse proxy and point ORBITALREG_HELP_URL at the chosen URL.

What goes here vs. docs/

Audience	Where
Code reviewers, RFC authors, in-repo browsing	docs/
Sales / evaluation / customer onboarding	docs-site/
Operator runbooks consumed during incidents	docs/operations/ (referenced from this site)
Per-resource API schema reference	Auto-generated via OpenAPI; rendered here

When in doubt, write the canonical content in docs/ and add a distilled / reorganised version here that links back.