Aller au contenu

ADR 0007 — MkDocs Material pour la living documentation

Contexte

Le kit a accumulé, vague après vague, des documents markdown, des HTML autoporteurs, un README canonique, un GUIDE.html exportable. À un certain moment, il faut une vitrine : un site consultable qui expose le tout, indexé, cherchable, agréable à parcourir.

Quatre contraintes :

  1. Markdown-first : les sources canoniques restent des fichiers markdown (voir ADR 0004).
  2. Langue française : l'indexation, les métadonnées, les accents doivent être respectés.
  3. Inclusion sans duplication : README.md, SDLC.md, les prompts, les agents doivent être inclus dans le site, pas copiés.
  4. Zero runtime : le site est statique, hébergeable sur n'importe quel serveur ou S3.

Options envisagées

  1. Docusaurus — React, très populaire, écosystème riche.
  2. VitePress — Vue, rapide, tendance.
  3. Hugo — Go, très rapide, massive adoption.
  4. MkDocs Material — Python, markdown-first, Material Design, plugins riches pour l'inclusion.

Décision

Retenu : MkDocs Material.

Le site est généré par mkdocs build depuis docs/. La configuration est dans mkdocs.yml. Les dépendances Python sont épinglées dans requirements-docs.txt. Quatre plugins critiques :

  • mkdocs-include-markdown-plugin — inclusion chirurgicale via marqueurs <!-- BEGIN:xxx --> (évite la duplication).
  • mkdocs-git-revision-date-localized-plugin — date de dernière mise à jour par page (indicateur de fraîcheur).
  • mkdocs-mermaid2-plugin — diagrammes Mermaid.
  • pymdown-extensions — admonitions, snippets, tooltips.

Conséquences

Positives :

  • Markdown-first : les fichiers docs/*.md sont lisibles directement sur GitHub, même sans MkDocs.
  • Inclusion propre : le README.md est inclus dans le site via marqueurs, sans être dupliqué — source unique préservée.
  • Qualité FR : la recherche MkDocs Material supporte l'indexation accentuée via search.lang: fr.
  • Générateurs compatibles : les pages générées (docs/portes/, docs/skills/) sont des fichiers markdown purs, portant un frontmatter generated: true.
  • Pas de JavaScript côté consommateur (à part Mermaid compilé côté build).

Négatives :

  • Dépendance Python pour le build. Mitigée : uniquement pour construire, pas pour consommer. Les consommateurs ouvrent du HTML.
  • Le thème Material est très reconnaissable — pas un problème, mais à noter.

Neutres :

  • Versions des plugins épinglées dans requirements-docs.txt pour éviter les régressions silencieuses sur une montée de version plugin.

Règle dérivée

Les sources canoniques ne sont jamais dupliquées dans docs/. Si un contenu doit figurer dans le site, soit il vit déjà dans docs/, soit il est inclus via include-markdown depuis son emplacement canonique (README.md, sdlc/SDLC.md, .github/prompts/*, .github/agents/*).

Non-objectifs de cette vague

  • Déploiement automatique (CI/CD, IONOS). Remis à une vague ultérieure.
  • Versioning multi-versions (mike). Pas nécessaire tant que le site reflète main.
  • Internationalisation. Le kit est mono-français.

Références