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).
`audit.html` and `users.html` cited ADR-0013 / ADR-0020 with anchors
pointing at `https://github.com/adr/madr` — that's the MADR _template_
repository, not our ADRs. Copy-paste artifact from the original
authoring.
Both links now resolve to the actual ADR file on Gitea
(`https://git.unespace.com/julien/apf_portal/src/branch/main/docs/decisions/…`)
so a reviewer who clicks lands on the right document. Surfacing the
ADRs inside portal-admin is intentionally out of scope — the audience
(APF internal admins, not architects) doesn't justify the
markdown-rendering + BFF-filesystem coupling cost; a separate static-
site for docs is a better fit and lands as its own chantier.
Julien Gautier