Aller au contenu principal

ADR-004 — Outillage de documentation : Docusaurus v3 auto-hébergé

Date : 2026-04-23 · Statut : Accepté

Contexte​

La documentation du projet est éparse, incomplète et non professionnelle :

  • 3 ADRs, architecture.md (850 lignes), design-system.md, README.md, CLAUDE.md
  • /docs/functional/ et /docs/technical/ = stubs vides sans contenu
  • Aucun guide utilisateur, aucune référence API, aucune règle de gestion documentée, aucun troubleshooting, aucun onboarding dev consolidé
  • Pas de navigation, pas de search, pas de versioning, pas d'i18n

Besoins identifiés :

  • Documentation fonctionnelle illustrée (captures d'écran à jour)
  • Documentation technique (architecture, schéma DB, code)
  • Design system navigable (tokens, composants, patterns)
  • API reference (Server Actions + REST minimal)
  • Règles de gestion métier (invariants financiers)
  • Guides utilisateur pas-à-pas
  • Bilingue FR + EN dès le départ
  • On-premise (même infra Coolify que l'app)

Options considérées​

Option A — Docusaurus v3 auto-hébergé (retenu)​

Pour

  • Sidebar multi-sections native
  • i18n intégré
  • MDX (composants React réutilisables dans la doc)
  • Search Lunr offline (pas de SaaS)
  • Versioning natif (activable à v1.0)
  • Écosystème mature, rendu professionnel par défaut

Contre

  • Stack React/Webpack supplémentaire à maintenir
  • ~150 deps npm
  • Build pipeline distinct

Option B — Nextra (Next.js-based)​

Pour : reste dans la stack Next.js existante, zéro nouvelle CI

Contre : i18n moins mature, sidebar multi-section moins flexible, versioning pauvre, search limité sans Algolia

Option C — Markdown brut sur GitHub​

Pour : zéro deps, zéro build, coût nul

Contre : pas de search transverse, pas d'i18n, pas de composants MDX, pas de rendu pro, pas d'auto-hébergement, navigation pauvre pour ~75 pages

Option D — MkDocs Material​

Pour : excellent thème par défaut, Python simple

Contre : MDX absent (pas de composants React interactifs pour le design system live), i18n moins fluide, stack Python dans un projet 100% TS

Décision​

Option A — Docusaurus v3 auto-hébergé.

Docusaurus est le seul outil couvrant simultanément les 7 axes requis (fonctionnel illustré, technique, design-system live, API, business rules, guides, déploiement) avec i18n natif et support MDX pour rendre les composants UI réels dans la documentation. L'auto-hébergement via un container nginx statique s'aligne avec la contrainte on-premise Coolify sans dépendance SaaS (Algolia exclu, Lunr local utilisé).

Conséquences​

Positives

  • Documentation centralisée dans docs-site/, un seul lieu canonique
  • Design system documenté avec composants React live (import réel depuis l'app)
  • Search offline compatible on-premise
  • CI bloquante : merge main refusé si build docs échoue ou broken link détecté
  • Scalabilité : versioning activable le jour où v1.0 shippera
  • Contenu dérivable du code généré via scripts (tokens, props composants, schéma Prisma, squelettes API)

Risques acceptés

  • Stack supplémentaire à maintenir (upgrade Docusaurus, deps React)
  • Build pipeline distinct (justifié par la séparation des préoccupations)
  • Volume initial important (~75 pages FR + stubs EN) — mitigé par phasage en 11 étapes et génération semi-auto

Révision​

Cette décision serait à remettre en question si :

  • Docusaurus v4 impose un changement majeur incompatible
  • L'équipe doc devient mono-page (MD brut suffirait)
  • Le besoin i18n disparaît et la stack React devient un coût net
  • Le projet migre vers une stack non-JS où MkDocs Material serait plus cohérent