fix(portal-admin): adr refs point at gitea, not the madr template repo #153

Merged

julien merged 2 commits from docs/adr-0022-docs-site-vitepress into main 2026-05-15 18:48:08 +02:00

Conversation 0 Commits 2 Files Changed 5

+177 -7

julien commented 2026-05-15 18:47:47 +02:00

Owner

Copy Link

Copy Source

Summary

Records the decision to render docs/**/*.md as a separately-deployed static site using VitePress + vitepress-plugin-mermaid.

This is ADR-only — the implementation (install + .vitepress/config.ts + docs/index.md + Gitea Actions workflow) lands as the next chantier. Splitting them keeps the decision review focused on the why before the how.

What lands

docs/decisions/0022-docs-site-vitepress.md

Full MADR 4.0.0 ADR. Decision drivers, 4 considered options (VitePress, MkDocs Material, Docusaurus 3, Astro Starlight), site-structure mapping, Mermaid integration, deployment + CI plan, consequences, revisit triggers. Tags: process, infrastructure.

Key choices captured:

• VitePress wins on toolchain alignment (Vite already in the workspace via @nx/vite, vite-plugin-angular, Vitest). MkDocs Material was the strong runner-up; the Python runtime tax in Gitea Actions tipped the balance.
• vitepress-plugin-mermaid for ```mermaid blocks (ADR-0009 sequence + architecture.md C4 are hard requirements).
• Site sources entirely from docs/. Mapping:
  • docs/index.md (new, Hero layout) → /
  • docs/development.md → /development
  • docs/architecture.md → /architecture
  • docs/decisions/README.md → /decisions/ (curated index, kept as section landing)
  • docs/decisions/00NN-….md → auto-listed in the sidebar by numeric prefix
  • docs/setup/0N-….md → /setup/0N-…
• Excluded via srcExclude: docs/README.md (stays as the git-side / IDE-preview index — option A from the prior discussion) and docs/decisions/template.md (authoring scaffold).
• Empty placeholder sections in docs/README.md (Operations runbooks, Security/perf/a11y rationales) are NOT pre-created as empty pages — they appear in the sidebar when real content lands.
• Deployment: dedicated hostname (provisional docs.portal.apf.fr) behind the same Caddy reverse-proxy as the apps, fed by a new .gitea/workflows/docs-site.yml triggered on docs/** push. Exact hostname follows the future infrastructure ADR; not locked here.

docs/decisions/README.md

ADR-0022 added to the index table.

CLAUDE.md

Bumps the ADR range from 0001 → 0021 to 0001 → 0022. New bullet in the "Architecture (recorded in ADRs)" section describing the docs-site choice in one paragraph. Implementation tracked in "Still on the roadmap" until the next PR lands it.

Notes for the reviewer

• Why ADR before implementation? The choice between VitePress / MkDocs Material / Docusaurus / Astro Starlight is exactly the "stable + recognized + innovative" trade-off CLAUDE.md asks to document. Reviewing the rationale on its own (without dragging through the install diff) keeps the discussion focused.
• Why not surface ADRs inside portal-admin? Audience mismatch — ADR-0020 §"Audience is disjoint" frames portal-admin around APF internal operators (CMS, audit, user directory), not architects. The full reasoning is in ADR-0022 §"Context and Problem Statement".
• Why two index artefacts (docs/README.md + future docs/index.md)? Option A from the structure discussion. Each serves a distinct audience: README.md is the flat link list that renders well in IDEs / Gitea source view; index.md will be the VitePress Hero landing for the web audience. Light duplication, no maintenance pressure (the IDE one only needs updating when sections appear/disappear).
• Why vitepress-plugin-mermaid rather than Docusaurus's built-in Mermaid? The community plugin is a sub-1.0 dependency on the wrapper (Mermaid itself is mature), but Mermaid is so mainstream that switching it out is a half-day rewrite if the plugin stalls. Trading that risk against Docusaurus's MDX-by-default footprint + React runtime is a net win.
• Why process + infrastructure tags? Mirrors ADR-0015 (also a CI / deploy decision with content authoring implications) and is consistent with the tag vocabulary. No new tag invented.

Test plan

• docs/decisions/0022-docs-site-vitepress.md validates as MADR 4.0.0 (frontmatter, section order). Index in docs/decisions/README.md updated in the same PR per ADR conventions.
• No code touched — lint / test / build matrix unaffected.
• Review for trade-off accuracy: did I get MkDocs Material's strengths right? Is Astro Starlight's maturity argument fair?
• Implementation chantier (next PR): pnpm add -D vitepress vitepress-plugin-mermaid mermaid, docs/.vitepress/config.ts, docs/index.md, .gitea/workflows/docs-site.yml, package.json scripts. Will land within the same week assuming this ADR holds.

What's next

If accepted as-is, the immediate follow-up is:

1. Install VitePress + the Mermaid plugin.
2. Author docs/.vitepress/config.ts with the sidebar shape spelled out in this ADR (auto-generated sub-sidebar for /decisions, hand-curated top-level).
3. Author docs/index.md (Hero layout).
4. Add the docs-site Gitea Actions workflow.
5. Wire the dev script (pnpm docs:dev) into package.json so contributors can preview locally.

If reviewers want to push back on the toolchain choice (MkDocs Material in particular has a strong case for the theme polish), this is the right PR to surface that — implementation hasn't started.

## Summary Records the decision to render `docs/**/*.md` as a separately-deployed static site using **VitePress + `vitepress-plugin-mermaid`**. This is **ADR-only** — the implementation (install + `.vitepress/config.ts` + `docs/index.md` + Gitea Actions workflow) lands as the next chantier. Splitting them keeps the decision review focused on the *why* before the *how*. ## What lands ### [`docs/decisions/0022-docs-site-vitepress.md`](docs/decisions/0022-docs-site-vitepress.md) Full MADR 4.0.0 ADR. Decision drivers, 4 considered options (VitePress, MkDocs Material, Docusaurus 3, Astro Starlight), site-structure mapping, Mermaid integration, deployment + CI plan, consequences, revisit triggers. Tags: `process`, `infrastructure`. **Key choices captured:** - VitePress wins on toolchain alignment (Vite already in the workspace via `@nx/vite`, `vite-plugin-angular`, Vitest). MkDocs Material was the strong runner-up; the Python runtime tax in Gitea Actions tipped the balance. - `vitepress-plugin-mermaid` for ```` ```mermaid ```` blocks ([ADR-0009](docs/decisions/0009-auth-flow-oidc-pkce-msal-node.md) sequence + [architecture.md](docs/architecture.md) C4 are hard requirements). - Site sources entirely from `docs/`. Mapping: - `docs/index.md` (new, Hero layout) → `/` - `docs/development.md` → `/development` - `docs/architecture.md` → `/architecture` - `docs/decisions/README.md` → `/decisions/` (curated index, kept as section landing) - `docs/decisions/00NN-….md` → auto-listed in the sidebar by numeric prefix - `docs/setup/0N-….md` → `/setup/0N-…` - **Excluded** via `srcExclude`: `docs/README.md` (stays as the git-side / IDE-preview index — option A from the prior discussion) and `docs/decisions/template.md` (authoring scaffold). - Empty placeholder sections in `docs/README.md` (Operations runbooks, Security/perf/a11y rationales) are NOT pre-created as empty pages — they appear in the sidebar when real content lands. - Deployment: dedicated hostname (provisional `docs.portal.apf.fr`) behind the same Caddy reverse-proxy as the apps, fed by a new `.gitea/workflows/docs-site.yml` triggered on `docs/**` push. Exact hostname follows the future infrastructure ADR; not locked here. ### [`docs/decisions/README.md`](docs/decisions/README.md) ADR-0022 added to the index table. ### [`CLAUDE.md`](CLAUDE.md) Bumps the ADR range from `0001 → 0021` to `0001 → 0022`. New bullet in the "Architecture (recorded in ADRs)" section describing the docs-site choice in one paragraph. Implementation tracked in "Still on the roadmap" until the next PR lands it. ## Notes for the reviewer - **Why ADR before implementation?** The choice between VitePress / MkDocs Material / Docusaurus / Astro Starlight is exactly the "stable + recognized + innovative" trade-off [CLAUDE.md](CLAUDE.md) asks to document. Reviewing the rationale on its own (without dragging through the install diff) keeps the discussion focused. - **Why not surface ADRs inside `portal-admin`?** Audience mismatch — [ADR-0020](docs/decisions/0020-portal-admin-app.md) §"Audience is disjoint" frames `portal-admin` around APF internal operators (CMS, audit, user directory), not architects. The full reasoning is in ADR-0022 §"Context and Problem Statement". - **Why two index artefacts (`docs/README.md` + future `docs/index.md`)?** Option A from the structure discussion. Each serves a distinct audience: `README.md` is the flat link list that renders well in IDEs / Gitea source view; `index.md` will be the VitePress Hero landing for the web audience. Light duplication, no maintenance pressure (the IDE one only needs updating when sections appear/disappear). - **Why `vitepress-plugin-mermaid` rather than Docusaurus's built-in Mermaid?** The community plugin is a sub-1.0 dependency on the wrapper (Mermaid itself is mature), but Mermaid is so mainstream that switching it out is a half-day rewrite if the plugin stalls. Trading that risk against Docusaurus's MDX-by-default footprint + React runtime is a net win. - **Why `process` + `infrastructure` tags?** Mirrors [ADR-0015](docs/decisions/0015-cicd-gitea-actions.md) (also a CI / deploy decision with content authoring implications) and is consistent with the [tag vocabulary](docs/decisions/README.md#tag-vocabulary). No new tag invented. ## Test plan - [x] `docs/decisions/0022-docs-site-vitepress.md` validates as MADR 4.0.0 (frontmatter, section order). Index in [`docs/decisions/README.md`](docs/decisions/README.md) updated in the same PR per [ADR conventions](docs/decisions/README.md#conventions). - [x] No code touched — `lint / test / build` matrix unaffected. - [ ] Review for trade-off accuracy: did I get MkDocs Material's strengths right? Is Astro Starlight's maturity argument fair? - [ ] Implementation chantier (next PR): `pnpm add -D vitepress vitepress-plugin-mermaid mermaid`, `docs/.vitepress/config.ts`, `docs/index.md`, `.gitea/workflows/docs-site.yml`, `package.json` scripts. Will land within the same week assuming this ADR holds. ## What's next If accepted as-is, the immediate follow-up is: 1. Install VitePress + the Mermaid plugin. 2. Author `docs/.vitepress/config.ts` with the sidebar shape spelled out in this ADR (auto-generated sub-sidebar for `/decisions`, hand-curated top-level). 3. Author `docs/index.md` (Hero layout). 4. Add the `docs-site` Gitea Actions workflow. 5. Wire the dev script (`pnpm docs:dev`) into `package.json` so contributors can preview locally. If reviewers want to push back on the toolchain choice (MkDocs Material in particular has a strong case for the theme polish), this is the right PR to surface that — implementation hasn't started.

julien added 2 commits 2026-05-15 18:47:48 +02:00

fix(portal-admin): adr refs point at gitea, not the madr template repo ... e1805f596d

`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.

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

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).

julien merged commit aa8ad97feb into main 2026-05-15 18:48:08 +02:00

julien deleted branch docs/adr-0022-docs-site-vitepress 2026-05-15 18:48:11 +02:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

adastra-bot (AdAstra Bot) julien (Julien Gautier)

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: julien/apf_portal#153