Documentation Codexia — conventions

Ce document décrit les conventions de structure, de nommage et de rédaction du dépôt de documentation Codexia.

Le dépôt est un dépôt de documentation pure au sens : pas de code produit / applicatif (le bundle Symfony et src/ ont été retirés — voir CHANGELOG.md). Son contenu se répartit en trois catégories à ne pas confondre :

1. La documentation : du Markdown et ses ressources (SVG, HTML d'aperçu, etc.).
2. L'outillage du dépôt (« Documentation as Code ») : .gitattributes, scripts/ (vérifs), .github/workflows/ (CI), scripts/hooks/. Ce sont des fichiers réels qui s'exécutent pour maintenir la qualité de la doc — pas du code produit.
3. Le code montré dans les .md (snippets de tutos, exemples) : du contenu illustratif, jamais exécuté par le dépôt.

Cartouche de document (front-matter)

Tout document de la documentation commence par un cartouche : un bloc de métadonnées YAML encadré par deux lignes ---, placé avant le titre #. Au rendu HTML du site, il est retiré du corps et réaffiché en encart ; il sert aussi de métadonnées de recherche pour le serveur MCP.

---
title: Déploiement VPS
skills: [sysadmin, secops, devops]
status: livré
type: reference
updated: 2026-06-02
summary: Mise en prod d'un VPS Ubuntu durci, Apache et HTTPS.
---

Champs — clés en anglais, valeurs en français. Tous obligatoires :

Règles :

• updated dans le cartouche remplace toute mention « Dernière mise à jour » en pied de page : ces pieds de page redondants sont supprimés (une seule source de date).
• status qualifie l'objet décrit : une fonctionnalité (livré = en prod / fini) comme un contenu éditorial (livré = rédigé et stable).
• Une valeur de skills absente de pilotage/competences.md est interdite.

Structure et nommage

Structure :

• Racine : documentation active (source de travail).
• inputs/legacy/ : copie figée des documents historiques (lecture seule).

racine/
├── <theme>/                             # Sous parties de <theme>
│   ├── <theme>-<sous theme A>.md        # Contenu spécifique au sous-thème A
│   └── <theme>-<sous theme B>.md        # Contenu spécifique au sous-thème B
├── <theme>.md                           # Contenu spécifique au thème
└── toc.md                               # Table des matières
inputs/legacy/                                  # LECTURE SEULE (copie figée des documents historiques)

Point d'entrée :

• toc.md pour la table des matières.

Consignes de mise à jour de la TOC :

• La TOC est unique et située à la racine : toc.md.
• Chaque nouveau document ajouté dans la documentation doit être référencé dans toc.md.
• Pas de sous-TOC par thème ; tout est listé dans la TOC principale.
• Les noms de fichiers sont en minuscules (slug).

Consignes de rédaction

• Tous les fichiers Markdown sont encodés en UTF-8.
• La documentation est rédigée en français, avec caractères accentués.
• Les arborescences de fichiers sont présentées en treeview ASCII.

Exemple d'arborescence pour documenter une extension Twig (Symfony) :

racine/
├── symfony/                             # Sous parties de Symfony
│   └── twig/                             # Dossier de l’extension Twig
│       ├── overview.md
│       ├── installation.md
│       ├── configuration.md
│       ├── usage.md
│       ├── filters.md
│       ├── functions.md
│       ├── tags.md
│       ├── tests.md
│       ├── troubleshooting.md
│       └── changelog.md
├── symfony.md                           # Contenu spécifique au thème Symfony
└── toc.md