Documentation pipeline

How the public site at libs.heritiersdudonjon.com is built — no manual steps after merging to main.

Principles

Layer	Tool	Source
Guides	VitePress	Markdown in docs/
API (./srd, ./character)	TypeDoc	TypeScript + TSDoc comments
UI catalog	Storybook	*.stories.tsx

Do not maintain a hand-written API reference (the old srd-data-api.md was removed for this reason).

Adding a .md file under docs/ is enough — update .vitepress/config.ts sidebar only when creating a new section folder.

SPA vs static content (important)

VitePress is a single-page app: same-origin links like /api/... or /storybook/ are handled by the client router, which has no page for those paths (you get the doc site's own 404).

Fix: in Markdown and in themeConfig.nav / sidebar, use absolute URLs for TypeDoc and Storybook, for example https://libs.heritiersdudonjon.com/api/modules/srd.html and https://libs.heritiersdudonjon.com/storybook/. Internal doc pages keep paths like /project/documentation-pipeline.

Source → URL

Source	Output path	Public URL (production)
docs/**/*.md	VitePress HTML	Same host, path /guide/..., /srd/..., etc.
src/srd, src/character	docs/public/api/	https://libs.heritiersdudonjon.com/api/...
Storybook build	docs/public/storybook/	https://libs.heritiersdudonjon.com/storybook/

Internal maintainer docs live in docs-internal/ (not published).

Commands

Command	Purpose
pnpm docs:dev	VitePress dev server (hot reload Markdown)
pnpm docs:api	Regenerate TypeDoc only
pnpm docs:build	Full site build (same as CI)
pnpm build	Required before Storybook (library dist/)

Build order (scripts/build-docs.mjs)

1. pnpm build — library dist/
2. typedoc → docs/public/api/
3. storybook build -o docs/public/storybook
4. vitepress build docs → docs/.vitepress/dist/

Common failures

Failure	Fix
Storybook cannot resolve package	Run pnpm build first
TypeDoc errors	Fix TS exports or typedoc.json exclusions
VitePress broken link	Fix Markdown links or sidebar paths

When to update what

Change	Action
New public export in src/srd/index.ts	Add TSDoc on symbol; no manual API markdown
New tutorial	Add docs/.../*.md
Architecture diagram	Edit docs/srd/architecture.md (Mermaid)
UI component	Storybook story + optional line in guide/ui.md
Breaking API	feat! commit + guide/migration.md

CI

• PR: docs job runs pnpm docs:build — must pass before merge.
• main: deploy-docs uploads docs/.vitepress/dist/ to OVH FTP (OVH_FTP_* secrets).

Decoupled from npm release — doc-only merges still deploy the site.

Configuration index

File	Role
docs/.vitepress/config.ts	Nav, sidebar, Mermaid
typedoc.json	API entry points
docs/public/.htaccess	SPA + /storybook/, /api/ passthrough
.storybook/	Storybook config

Agents

• Edit Markdown or TSDoc, then run pnpm docs:build locally.
• Do not recreate website/ or manual content/index.ts registries.
• See Library contract and root AGENTS.md.