Docs source of truth

Hermes Switch UI — Docs Authoring Pipeline

One markdown tree powers both the authenticated Switch UI app docs and the public Astro/Starlight website docs.

Docs authoring pipeline Root docs markdown flows to both Switch UI app docs and Astro Starlight website docs. Assets are served through app API routes or static docs-assets files depending on target. AUTHORING BUILD / RENDER USER-FACING ROUTES docs/*.md canonical markdown frontmatter + content docs-manifest.yaml app docs sidebar slug registry astro.config.mjs Starlight website sidebar reads root docs/ Switch UI app renderer docs-content.ts + docs-render.ts auth-aware /docs surface Astro + Starlight content collection + custom CSS static public docs build Assets + diagrams images, screenshots, HTML sync-docs-assets.mjs App docs http://localhost:3000/docs /api/docs-asset for media Website docs https://hermes-switchui.zi0n.space/docs/ static /docs-assets/ media Embedded preview Switch UI /website/docs/ same Starlight build, base-aware Rule: edit markdown once in repo-root docs/. Build targets rewrite links/assets for their own base path; do not duplicate docs under website/.

Canonical source

Write and review markdown in the repo-root docs/ folder. Website docs and app docs should not fork content.

Two sidebars

The app sidebar is manifest-driven. The public website sidebar is Starlight config-driven, but both point at the same slugs.

Asset rewrite

Use app-safe iframe and image paths in markdown. The website build copies and rewrites them to static /docs-assets/ URLs.

Hermes Switch UI · Root docs → app docs + Astro/Starlight website docs