Tenir le dossier de référence en Markdown versionné dans Git
Le dossier est un site statique généré depuis des fichiers Markdown avec frontmatter, un fichier par information, validé automatiquement.
- Identifiant
- ADR-006
- Statut
- Acceptée
- Date
- 16 septembre 2026
- Décision
- Le contenu vit dans content/ en Markdown + frontmatter YAML (un fichier = une information), rendu par Next.js ; pas de base de données en V1.
- Options étudiées
- Markdown + Git + site statique
- Wiki (Wiki.js, Outline, Notion)
- Base de données + éditeur web
Contexte
Le projet accumule des recherches, des décisions, des benchmarks, des sources. Le risque principal est de ne plus rien retrouver. Il faut un support durable, versionné, lisible dans dix ans, indexable plus tard par une IA, et qui produise des diffs compréhensibles.
Options étudiées
- Markdown + Git : fichiers texte, diffs lisibles, aucun verrou propriétaire, schéma de frontmatter validable, édition dans n'importe quel éditeur ; pas d'édition en ligne en V1.
- Wiki : édition en ligne confortable, mais export et versionnement médiocres, schéma faible.
- Base de données : puissant mais sur-architecturé pour un auteur unique.
Décision
Markdown avec frontmatter validé par des schémas, un fichier par entrée (page, note, décision, benchmark, source…), relations par références explicites, site généré statiquement. Une base de données, l'authentification ou l'édition en ligne pourront s'ajouter plus tard sans changer le format du contenu.
Pourquoi
Le contenu reste la source de vérité et survit à l'outil. Le frontmatter typé permet les vues spécialisées (tableaux, matrices, dashboard) sans dupliquer les données. Chaque commit documente l'évolution du projet.
Conséquences
- Les conventions sont documentées dans le guide de contenu et vérifiées par un script.
- L'ajout d'une nouvelle collection nécessite un schéma et une entrée dans le registre des sections (quelques lignes).
- Le contenu est directement découpable en chunks pour un futur RAG « interroger mon dossier ».