docs(adr-0022): documentation site — vitepress + mermaid plugin

Records the decision to render `docs/**/*.md` as a separately-deployed static site using VitePress (Vite-based, Node-only toolchain) with `vitepress-plugin-mermaid` for the existing C4 + sequence diagrams. Site mapping: docs/index.md (new, Hero layout) → / docs/development.md → /development docs/architecture.md → /architecture docs/decisions/README.md → /decisions/ docs/decisions/00NN-…md → /decisions/00NN-… (auto sidebar) docs/setup/0N-…md → /setup/0N-… `docs/README.md` stays as the git-side / IDE-preview index and is excluded from the published site. `docs/decisions/template.md` is likewise excluded — authoring scaffold, not reader content. Audience is internal (RSSI, devs, ops). Surfacing inside portal-admin was considered and rejected — ADR-0020 §"Audience is disjoint" frames portal-admin around operational workloads, not architecture review. A decoupled site keeps the boundary clean. Toolchain alignment is the deciding factor over MkDocs Material: adding a Python runtime to Gitea Actions is a permanent maintenance tax we can avoid by reusing the Vite stack already in the workspace. Docusaurus + Astro Starlight are documented in "Pros and cons" as runner-up + revisit-later options. Implementation lands as a separate chantier (`.vitepress/config.ts`, `docs/index.md`, Gitea Actions workflow, `package.json` scripts).
2026-05-15 18:45:26 +02:00
parent e1805f596d
commit eebe20bc6f
3 changed files with 163 additions and 1 deletions
@@ -65,3 +65,4 @@ ADRs are listed in numerical order. To slice by topic, filter on the `Tags` colu
 | [0019](0019-internationalisation-angular-localize.md)        | Internationalisation — `@angular/localize`, build-time per-locale bundles, `/fr` + `/en` path-based routing      | accepted | `frontend`, `accessibility`, `performance`, `process`          | 2026-05-11 |
 | [0020](0020-portal-admin-app.md)                             | `portal-admin` — dedicated SPA for portal administration, sharing the existing BFF                               | accepted | `frontend`, `backend`, `security`, `infrastructure`, `process` | 2026-05-11 |
 | [0021](0021-phase-2-security-baseline.md)                    | Phase-2 security baseline — helmet, CORS allowlist, double-submit CSRF, rate limiting, structured error envelope | accepted | `security`, `backend`                                          | 2026-05-13 |
+| [0022](0022-docs-site-vitepress.md)                          | Documentation site — VitePress + Mermaid plugin, separate static deployment                                      | accepted | `process`, `infrastructure`                                    | 2026-05-15 |