feat(docs): vitepress site for docs/, mermaid rendering, ci build workflow (#154)
## Summary
Implementation of [ADR-0022](docs/decisions/0022-docs-site-vitepress.md). Stands up the static documentation site that renders `docs/**/*.md` (architecture diagrams, daily-dev guide, ADRs, onboarding) via **VitePress + `vitepress-plugin-mermaid`**, behind a Gitea Actions build gate.
Local dev: `pnpm docs:dev`. Full build: `pnpm docs:build` (~9 s, output in `docs/.vitepress/dist/`).
## What lands
### Dependencies
`vitepress 1.6.4`, `vitepress-plugin-mermaid 2.0.17`, `mermaid 11.15.0` — workspace devDependencies. No runtime impact on `portal-shell` / `portal-admin` / `portal-bff`.
### [`docs/.vitepress/config.mts`](docs/.vitepress/config.mts)
The single source of truth for the site. Highlights:
- **`srcExclude`** drops `docs/README.md` (git/IDE-only index per ADR-0022's option A) and `docs/decisions/template.md` (authoring scaffold).
- **`rewrites`** maps `decisions/README.md` → `decisions/index.md` so `/decisions/` resolves to the curated tag-grouped landing while the source filename stays git-conventional.
- **`ignoreDeadLinks`** skips:
- `localhost:*` URLs (Jaeger, OTLP — only resolve in a live dev session),
- cross-repo references (`../CLAUDE`, `../../apps/**`, `../../infra/**`, `../../notes/**`) — intentional from git/IDE consumers; not the site's job to render them,
- excluded targets (`./template`, `./README`) — file exists in the repo, just not in the site.
- **Auto-sidebar for `/decisions/`** — `adrSidebarItems()` walks `docs/decisions/00*-*.md` and emits sorted `ADR-NNNN — title` entries. Adding an ADR is a single-file change, no `config.mts` edit.
- **Hand-curated top-level nav** (Development, Architecture, Decisions, Onboarding).
- **Mermaid via `withMermaid()`** with `securityLevel: 'strict'` so diagrams can't inject arbitrary HTML.
### [`docs/index.md`](docs/index.md)
VitePress Hero landing with four feature cards (Architecture, Decisions, Development, Onboarding).
### [`docs/development.md`](docs/development.md) — two surgical fixes
- Line ~5: `[setup/](setup/)` → `[setup/01-wsl-terminal-setup.md](setup/01-wsl-terminal-setup.md)`. Folder-style links don't resolve cleanly under `cleanUrls: true`; pointing at the first onboarding page is both correct and useful.
- Line 330: wrap `${{ github.* }}` in `<code v-pre>…</code>`. VitePress runs every Markdown file through the Vue template compiler, which sees the inline `{{ … }}` as an interpolation. `v-pre` keeps the literal text intact. The rest of the source is unaffected.
### [`package.json`](package.json)
Three new scripts:
```
docs:dev → vitepress dev docs
docs:build → vitepress build docs
docs:preview → vitepress preview docs
```
Pure pnpm scripts, no Nx project — the site has no cross-project dependency graph to track.
### [`.gitea/workflows/docs-site.yml`](.gitea/workflows/docs-site.yml)
Triggers on push to `main` and on PR, scoped by `paths:` to `docs/**`, `package.json`, `pnpm-lock.yaml`, and the workflow itself. Three steps:
1. `pnpm install --frozen-lockfile`
2. `pnpm docs:build`
3. Regression fence: `grep` ADR-0009's rendered HTML for `class="mermaid"` or `<svg>` so a silent Mermaid-plugin breakage on a major upgrade fails the workflow rather than ship a site with raw code blocks where diagrams should be.
4. On push only: upload `docs/.vitepress/dist/` as a `docs-site` artifact (30-day retention). The actual rsync to the static host lands when the future infrastructure ADR locks the deployment target.
### [`.gitignore`](.gitignore)
Excludes `docs/.vitepress/{cache,dist}/` so local builds don't leak into commits.
## Notes for the reviewer
- **Why `config.mts` and not `config.ts`?** VitePress is ESM-only, and `vitepress-plugin-mermaid` follows. Vite loads `.ts` config files via its CJS bundler in this workspace's setup and chokes on the ESM imports. `.mts` flips the loader to ESM and the build succeeds. Same pattern is used elsewhere in the workspace (`jest.config.cts`, app `vite.config.mts`).
- **Why no Nx project (`docs/project.json`)?** The doc site has no Nx-trackable dependencies (it consumes `.md` files, not TypeScript projects). Putting it in the Nx graph adds ceremony with no caching benefit — VitePress's incremental rebuilds are sub-second already, and the site never has cross-project `affected` semantics. Pure pnpm scripts keep the surface small.
- **Why the regression fence on Mermaid?** ADR-0022 §"Confirmation" promises it. The plugin is a community dep (sub-1.0 wrapper around the official Mermaid renderer); a major upgrade or a Mermaid runtime change could leave fenced ` ```mermaid ` blocks rendered as raw code without anyone noticing — until an RSSI clicks ADR-0009 and sees no diagram. Cheap grep gate, real signal.
- **Why upload as artifact, not deploy?** Per [ADR-0022](docs/decisions/0022-docs-site-vitepress.md) §"Deployment & CI": the host (`docs.portal.apf.fr` or a sub-path) is provisional. Locking an rsync target now would couple this PR to a not-yet-made infra decision. Artifact upload is the staging mechanism — manual drop on the host until the infrastructure ADR formalises the target.
- **Why `ignoreDeadLinks` rather than fixing every cross-repo reference?** The cross-repo links are genuinely useful from a git/IDE perspective (where the docs/ markdown is browsed alongside the rest of the codebase). Rewriting them to `https://git.unespace.com/julien/apf_portal/src/branch/main/…` would make them work on the site but lose the IDE quick-jump. Skipping at site-build time is the right trade-off — the site reader gets a graceful "link doesn't exist here" if they click, the IDE reader gets a working jump.
## Test plan
- [x] `pnpm docs:build` succeeds in ~9 s. Output at `docs/.vitepress/dist/` contains an `index.html`, every ADR, the development guide, the architecture diagrams, and the three setup pages.
- [x] Mermaid renders: `grep 'class="mermaid"' docs/.vitepress/dist/decisions/0009-…html` returns a match.
- [x] `pnpm exec nx run-many -t format:check lint test build` for the 6 main projects — 18/18 tasks green, no Nx regression from the new top-level config.
- [ ] **Manual smoke**: `pnpm docs:dev`, open `http://localhost:5173`, walk through:
- Landing renders Hero + 4 feature cards.
- Search box returns hits for "audit", "MFA", "OBO".
- `/decisions/0009-…` renders the OIDC sequence diagram (Mermaid SVG, not raw text).
- `/decisions/0010-…` ERD or `/architecture` C4 diagrams likewise.
- Dark-mode toggle flips diagrams to dark theme without page reload.
- Sidebar shows the 22 ADRs auto-listed under `/decisions/`.
- The "Decisions" curated index at `/decisions/` lists ADRs by tag (no regression on the source markdown).
## What's next
Once the deployment target is fixed (future infra ADR), wire the rsync step into the workflow — that lands as a small follow-up PR. Until then the artifact carries the bundle.
---------
Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr>
Reviewed-on: #154
This commit was merged in pull request #154.
This commit is contained in:
@@ -0,0 +1,73 @@
|
||||
# Per ADR-0022 (Documentation site — VitePress).
|
||||
# Builds the static docs site from `docs/`. On `pull_request` the
|
||||
# build is a syntax / dead-link gate; on `push` to `main` the same
|
||||
# build runs and the bundle is uploaded as an artifact so the
|
||||
# operator can drop it on the static host until the future
|
||||
# infrastructure ADR locks the rsync target.
|
||||
#
|
||||
# Path filter scopes the workflow to changes that can actually
|
||||
# affect the rendered site: documentation content, the VitePress
|
||||
# configuration itself, and dependency manifests (Vite/VitePress
|
||||
# upgrades).
|
||||
|
||||
name: Docs site
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
branches: [main]
|
||||
paths:
|
||||
- 'docs/**'
|
||||
- 'package.json'
|
||||
- 'pnpm-lock.yaml'
|
||||
- '.gitea/workflows/docs-site.yml'
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- 'docs/**'
|
||||
- 'package.json'
|
||||
- 'pnpm-lock.yaml'
|
||||
- '.gitea/workflows/docs-site.yml'
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: [self-hosted, on-prem]
|
||||
steps:
|
||||
- uses: actions/checkout@v6
|
||||
- uses: pnpm/action-setup@v6
|
||||
- uses: actions/setup-node@v6
|
||||
with:
|
||||
node-version-file: '.nvmrc'
|
||||
cache: 'pnpm'
|
||||
- run: pnpm install --frozen-lockfile
|
||||
# `pnpm docs:build` runs `vitepress build docs` per the script
|
||||
# added in this chantier. Fails the workflow on:
|
||||
# - markdown / Vue-template parse errors,
|
||||
# - genuine dead in-site links (the config's
|
||||
# `ignoreDeadLinks` regex already covers the intentional
|
||||
# cross-repo + localhost references that must not break
|
||||
# the build).
|
||||
- name: Build docs site
|
||||
run: pnpm docs:build
|
||||
# Sanity-check: the build must produce HTML where the Mermaid
|
||||
# plugin has injected its diagram markers. Guards against a
|
||||
# silent regression on the plugin upgrade path — `pnpm install`
|
||||
# might happily resolve a new major that no longer hooks into
|
||||
# markdown-it the same way, leaving fenced ```mermaid blocks
|
||||
# as raw text. Per ADR-0022 §"Confirmation".
|
||||
- name: Assert Mermaid renders into the build output
|
||||
run: |
|
||||
if ! grep -RIlq 'class="mermaid"\|<svg' docs/.vitepress/dist/decisions/0009-auth-flow-oidc-pkce-msal-node.html; then
|
||||
echo "ADR-0009's Mermaid sequence diagram did not render — Mermaid plugin regression?" >&2
|
||||
exit 1
|
||||
fi
|
||||
# On push only — upload the static bundle so the operator can
|
||||
# rsync it to the host until the future infra ADR formalises
|
||||
# the deployment target. The artifact lives 30 days in Gitea's
|
||||
# storage by default.
|
||||
- name: Upload docs bundle
|
||||
if: github.event_name == 'push'
|
||||
uses: actions/upload-artifact@v3
|
||||
with:
|
||||
name: docs-site
|
||||
path: docs/.vitepress/dist/
|
||||
retention-days: 30
|
||||
@@ -10,6 +10,10 @@ tmp/
|
||||
.nx/cache/
|
||||
.nx/workspace-data/
|
||||
|
||||
# VitePress (docs site per ADR-0022)
|
||||
docs/.vitepress/cache/
|
||||
docs/.vitepress/dist/
|
||||
|
||||
# Test artifacts
|
||||
coverage/
|
||||
.test-output/
|
||||
|
||||
@@ -0,0 +1,164 @@
|
||||
import { readdirSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { defineConfig } from 'vitepress';
|
||||
import { withMermaid } from 'vitepress-plugin-mermaid';
|
||||
|
||||
/**
|
||||
* VitePress configuration for the APF Portal documentation site
|
||||
* per ADR-0022.
|
||||
*
|
||||
* Source tree maps directly to URLs:
|
||||
* docs/index.md → /
|
||||
* docs/development.md → /development
|
||||
* docs/architecture.md → /architecture
|
||||
* docs/decisions/README.md → /decisions/
|
||||
* docs/decisions/00NN-…md → /decisions/00NN-… (auto-listed sidebar)
|
||||
* docs/setup/0N-…md → /setup/0N-…
|
||||
*
|
||||
* `docs/README.md` stays as the git-side / IDE-preview index and is
|
||||
* therefore excluded from the published site; `decisions/template.md`
|
||||
* is an authoring scaffold, also excluded.
|
||||
*/
|
||||
|
||||
const DECISIONS_DIR = join(__dirname, '..', 'decisions');
|
||||
const ADR_FILE_RE = /^\d{4}-[\w-]+\.md$/;
|
||||
|
||||
/**
|
||||
* Walks `docs/decisions/` and returns one sidebar entry per accepted
|
||||
* ADR (`NNNN-kebab-title.md`), ordered by numeric prefix. Adding a
|
||||
* new ADR is then a single-file change — no `config.ts` edit
|
||||
* required (the convention spelled out in ADR-0022 §"Sidebar
|
||||
* generation").
|
||||
*
|
||||
* The link text drops the numeric prefix's leading zeroes to read
|
||||
* naturally ("ADR-0009 — …") while the underlying URL keeps the
|
||||
* full filename for stable routing across renames.
|
||||
*/
|
||||
function adrSidebarItems(): { text: string; link: string }[] {
|
||||
return readdirSync(DECISIONS_DIR)
|
||||
.filter((name) => ADR_FILE_RE.test(name))
|
||||
.sort()
|
||||
.map((name) => {
|
||||
const slug = name.replace(/\.md$/, '');
|
||||
const num = slug.slice(0, 4);
|
||||
const title = slug.slice(5).replace(/-/g, ' ');
|
||||
return {
|
||||
text: `ADR-${num} — ${title}`,
|
||||
link: `/decisions/${slug}`,
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
export default withMermaid(
|
||||
defineConfig({
|
||||
title: 'APF Portal Documentation',
|
||||
description:
|
||||
"Architecture decisions, development guide, and onboarding material for APF France Handicap's web portal.",
|
||||
|
||||
// Root files (`README.md`) and authoring artefacts (`template.md`)
|
||||
// never make it to the rendered site — see ADR-0022.
|
||||
srcExclude: ['README.md', 'decisions/template.md'],
|
||||
|
||||
// The curated decisions index lives in `decisions/README.md`
|
||||
// (git/IDE convention). VitePress expects `index.md` at a
|
||||
// folder root for clean URLs, so we rewrite at build time —
|
||||
// source layout stays git-friendly, the published URL resolves
|
||||
// `/decisions/` to the curated landing.
|
||||
rewrites: {
|
||||
'decisions/README.md': 'decisions/index.md',
|
||||
},
|
||||
|
||||
// ADRs and the development guide carry deliberate references to
|
||||
// files that live OUTSIDE `docs/` (CLAUDE.md, apps/**, infra/**,
|
||||
// notes/**), localhost URLs that only resolve in a dev session,
|
||||
// and the authoring `template.md` we explicitly excluded. All of
|
||||
// those are valid from a git/IDE reader's perspective; VitePress
|
||||
// is told to skip them rather than fail the build.
|
||||
ignoreDeadLinks: [
|
||||
/^https?:\/\/localhost/,
|
||||
/^\.{1,2}\//,
|
||||
/\/template$/,
|
||||
/\/README$/,
|
||||
],
|
||||
|
||||
// VitePress emits `.html` files by default; clean URLs hide the
|
||||
// extension. Mirrors what readers will see in the browser address
|
||||
// bar and what the inline ADR refs in `portal-admin` already use
|
||||
// when they target Gitea source-view (forward-compatible the day
|
||||
// we flip those refs to point at the docs site).
|
||||
cleanUrls: true,
|
||||
|
||||
// The site is internal + read-only; we let crawlers in by
|
||||
// default but won't ship a sitemap until the hostname is locked
|
||||
// by the future infra ADR.
|
||||
lastUpdated: true,
|
||||
|
||||
themeConfig: {
|
||||
nav: [
|
||||
{ text: 'Development', link: '/development' },
|
||||
{ text: 'Architecture', link: '/architecture' },
|
||||
{ text: 'Decisions', link: '/decisions/' },
|
||||
{ text: 'Onboarding', link: '/setup/01-wsl-terminal-setup' },
|
||||
],
|
||||
|
||||
sidebar: {
|
||||
'/development': [
|
||||
{
|
||||
text: 'Daily development',
|
||||
items: [{ text: 'Repo layout & commands', link: '/development' }],
|
||||
},
|
||||
],
|
||||
'/architecture': [
|
||||
{
|
||||
text: 'Architecture',
|
||||
items: [{ text: 'C4 + module boundaries', link: '/architecture' }],
|
||||
},
|
||||
],
|
||||
'/decisions/': [
|
||||
{
|
||||
text: 'Decisions',
|
||||
items: [
|
||||
{ text: 'Index by theme', link: '/decisions/' },
|
||||
...adrSidebarItems(),
|
||||
],
|
||||
},
|
||||
],
|
||||
'/setup/': [
|
||||
{
|
||||
text: 'Onboarding',
|
||||
items: [
|
||||
{ text: 'WSL terminal setup', link: '/setup/01-wsl-terminal-setup' },
|
||||
{ text: 'Dev web stack', link: '/setup/02-dev-web-stack' },
|
||||
{ text: 'Angular + Nx monorepo', link: '/setup/03-angular-nx-monorepo' },
|
||||
],
|
||||
},
|
||||
],
|
||||
},
|
||||
|
||||
socialLinks: [
|
||||
{ icon: 'git', link: 'https://git.unespace.com/julien/apf_portal' },
|
||||
],
|
||||
|
||||
search: {
|
||||
provider: 'local',
|
||||
},
|
||||
|
||||
outline: {
|
||||
level: [2, 3],
|
||||
},
|
||||
|
||||
footer: {
|
||||
message: 'APF Portal — internal documentation',
|
||||
},
|
||||
},
|
||||
|
||||
// `vitepress-plugin-mermaid` passes its `mermaid` key through to
|
||||
// the Mermaid runtime. Theme `default` follows VitePress's
|
||||
// light/dark switcher automatically; explicit `securityLevel`
|
||||
// tightens the renderer so diagrams can't inject arbitrary HTML
|
||||
// from the source markdown.
|
||||
mermaid: {
|
||||
securityLevel: 'strict',
|
||||
},
|
||||
}),
|
||||
);
|
||||
+2
-2
@@ -2,7 +2,7 @@
|
||||
|
||||
This document is the day-to-day reference for working on `apf_portal`. It covers the repo layout, the prerequisites, the initial setup from a fresh clone, and the commands you'll run during a typical development cycle. It is meant to grow — add sections as the team's workflow does.
|
||||
|
||||
For decision rationale, see the [ADRs](decisions/). For onboarding the local environment (terminal, Node, pnpm), see [setup/](setup/).
|
||||
For decision rationale, see the [ADRs](decisions/). For onboarding the local environment (terminal, Node, pnpm), see [setup/01-wsl-terminal-setup.md](setup/01-wsl-terminal-setup.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -327,7 +327,7 @@ Renovate authenticates as a dedicated bot user. Setup is manual on Gitea — don
|
||||
4. **Generate a PAT for the bot** (`RENOVATE_TOKEN`). Sign in as the bot, then User Settings → Applications → Generate New Token. Scopes needed: read/write `repository`, read/write `issue`, read `user`. Avoid `admin`.
|
||||
5. **Store the PAT as a repo secret.** Settings → Actions → Secrets → New Secret. Name: `RENOVATE_TOKEN`. Value: the token from step 4.
|
||||
6. **Generate a zero-scope GitHub.com PAT** (`GITHUBCOM_TOKEN`). On github.com (any account, e.g. yours): Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic). **Do not tick any scope** — anonymous-equivalent rights are enough; the token only buys Renovate the higher authenticated rate limit (5 000 req/h vs 60 req/h) for resolving GitHub-hosted Action versions and `containerbase/node-prebuild` binaries used during lockfile maintenance.
|
||||
7. **Store it as a repo secret named `GITHUBCOM_TOKEN`** (Gitea reserves the `GITHUB_*` secret namespace for the built-in `${{ github.* }}` context, so an underscore between `GITHUB` and `COM` is rejected).
|
||||
7. **Store it as a repo secret named `GITHUBCOM_TOKEN`** (Gitea reserves the `GITHUB_*` secret namespace for the built-in <code v-pre>${{ github.\* }}</code> context, so an underscore between `GITHUB` and `COM` is rejected).
|
||||
8. **Sign out and forget both tokens locally.** They are now only retrievable via the secret store.
|
||||
|
||||
To **rotate** either token: regenerate at the matching step, update the secret. The schedule keeps running unattended.
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
layout: home
|
||||
|
||||
hero:
|
||||
name: APF Portal
|
||||
text: Documentation
|
||||
tagline: Architecture decisions, development guide, and onboarding material for APF France Handicap's web portal.
|
||||
actions:
|
||||
- theme: brand
|
||||
text: Read the architecture
|
||||
link: /architecture
|
||||
- theme: alt
|
||||
text: Browse decisions
|
||||
link: /decisions/
|
||||
|
||||
features:
|
||||
- title: Architecture
|
||||
details: System context, container diagram, Nx module boundaries, CI/CD pipeline. Cross-cutting Mermaid diagrams that frame the whole platform.
|
||||
link: /architecture
|
||||
linkText: Open architecture
|
||||
- title: Decisions (ADRs)
|
||||
details: Every non-trivial choice — auth flow, sessions, audit trail, downstream-API access, accessibility, performance budgets, admin app — recorded as MADR 4.0.0 ADRs.
|
||||
link: /decisions/
|
||||
linkText: Open decisions
|
||||
- title: Development guide
|
||||
details: Repo layout, daily commands, observability dev-loop (Jaeger, log↔trace correlation), dependency updates, conventional commits.
|
||||
link: /development
|
||||
linkText: Open development guide
|
||||
- title: Onboarding
|
||||
details: WSL terminal setup, Node + pnpm + Docker, Angular + Nx monorepo bootstrap. Everything a new contributor needs to get a working environment.
|
||||
link: /setup/01-wsl-terminal-setup
|
||||
linkText: Start onboarding
|
||||
---
|
||||
+7
-1
@@ -9,7 +9,10 @@
|
||||
"ci:audit": "pnpm audit --audit-level=moderate",
|
||||
"ci:commits": "pnpm exec commitlint --from ${COMMIT_LINT_FROM:-origin/main} --to HEAD --verbose",
|
||||
"ci:gzip-budgets": "node scripts/check-gzip-budgets.mjs",
|
||||
"ci:perf": "pnpm exec nx build portal-shell --configuration=production && pnpm ci:gzip-budgets && pnpm exec lhci autorun --config=./lighthouserc.js"
|
||||
"ci:perf": "pnpm exec nx build portal-shell --configuration=production && pnpm ci:gzip-budgets && pnpm exec lhci autorun --config=./lighthouserc.js",
|
||||
"docs:dev": "vitepress dev docs",
|
||||
"docs:build": "vitepress build docs",
|
||||
"docs:preview": "vitepress preview docs"
|
||||
},
|
||||
"private": true,
|
||||
"lint-staged": {
|
||||
@@ -101,6 +104,7 @@
|
||||
"jsdom": "^29.0.0",
|
||||
"jsonc-eslint-parser": "^2.1.0",
|
||||
"lint-staged": "^17.0.0",
|
||||
"mermaid": "^11.15.0",
|
||||
"nx": "22.7.1",
|
||||
"pino-pretty": "^13.1.3",
|
||||
"postcss": "^8.5.12",
|
||||
@@ -113,6 +117,8 @@
|
||||
"typescript": "~5.9.2",
|
||||
"typescript-eslint": "^8.40.0",
|
||||
"vite": "^8.0.0",
|
||||
"vitepress": "^1.6.4",
|
||||
"vitepress-plugin-mermaid": "^2.0.17",
|
||||
"vitest": "^4.0.8",
|
||||
"webpack-cli": "^5.1.4"
|
||||
},
|
||||
|
||||
Generated
+1922
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user