Markdown Codexia

Ce document définit la spécification Markdown utilisée par Codexia.

Objectif

• Assurer une compatibilité maximale avec les rendus Markdown standards.
• Ajouter des fonctions internes pour la documentation (ex: include) sans casser l'affichage dans un éditeur par défaut.
• Produire un HTML final accessible (WCAG 2.1 AA).

Références

• Markdown (origine): https://daringfireball.net/2004/03/introducing_markdown
• Markdown 1.0: https://daringfireball.net/2004/08/markdown_10
• Markdown 1.0.1: https://daringfireball.net/2004/12/markdown_101
• CommonMark Spec: https://spec.commonmark.org/
• GitHub Flavored Markdown (GFM): https://github.github.com/gfm/

Profil supporté (CDX-MD 1)

Base CommonMark

Le cœur de la spec est CommonMark. Toute syntaxe CommonMark doit être acceptée et rendue correctement.

Extensions GFM activées

Codexia active les extensions GFM suivantes:

• Tables
• Task lists
• Strikethrough
• Autolinks (URLs et emails)
• Fenced code blocks avec info string

HTML brut

• HTML brut autorisé mais filtré (whitelist) au rendu final.
• Les balises non autorisées sont supprimées ou échappées.

Implémentations courantes (différences à connaître)

Le rendu peut varier selon la plateforme car les extensions activées diffèrent:

• GitHub: GFM complet, avec extensions propres.
• GitLab: proche de GFM, avec extensions spécifiques.
• Autres éditeurs: support partiel ou strict CommonMark.

Conséquence: tout document doit rester lisible en CommonMark pur, puis s'améliorer avec GFM/extension Codexia.

Extensions Codexia (directives internes)

Les directives sont écrites en commentaires HTML pour rester invisibles dans les éditeurs Markdown standards.

Règles générales

• Les directives doivent être pré-traitées côté application avant rendu Markdown final.
• Les directives inconnues sont ignorées sans erreur.
• Une directive ne doit pas modifier l'affichage dans un rendu CommonMark "pur".

Directive include (prioritaire)

Syntaxe recommandée:

<!-- cdx:include("guides/intro.md") -->

Variante courte tolérée:

<!-- cdx:include guides/intro.md -->

Fallback lisible (conseillé):

<!-- cdx:include("guides/intro.md") -->
[Lire la suite](guides/intro.md)

Règles d'inclusion:

• Chemin relatif au dépôt documentation (racine du repo).
• Interdiction des chemins absolus et des traversées (..).
• Détection des boucles (max 5 niveaux d'inclusion).
• Si le fichier est introuvable: conserver le fallback éventuel, sinon rendre un avertissement non bloquant.

Fonctions internes (style Twig)

Codexia prévoit un mécanisme de fonctions internes inspiré de Twig, exprimé via directives:

• include(path) est la première fonction supportée.
• Les futures fonctions doivent suivre la même forme.

Exemple de forme canonique:

<!-- cdx:fn name="include" path="guides/intro.md" -->

Rendu HTML accessible (obligatoire)

Le rendu final doit viser WCAG 2.1 AA. Règles minimales:

• Titres: hiérarchie cohérente, pas de sauts de niveaux (h2 après h1, etc.).
• Images: texte alternatif obligatoire, alt="" autorisé uniquement si décoratif.
• Liens: libellé explicite, pas de "cliquez ici" isolé.
• Tableaux: génération de <thead> et <tbody>, en-têtes en <th scope="col">.
• Task lists: rendu en checkboxes désactivées avec aria-label.
• Code: <pre><code> avec classe language-xxx si info string, pas de perte de contenu.
• HTML brut: filtrage strict, aucune balise qui casse la navigation clavier ou la sémantique.

Pipeline de rendu recommandé

1. Pré-traitement des directives Codexia.
2. Parsing Markdown (CommonMark + GFM).
3. Génération HTML.
4. Post-traitement accessibilité (titres, tables, checklists, alt, etc.).
5. Sanitization finale (whitelist HTML).

Roadmap Markdown

Il n'existe pas de roadmap unique officielle. La stratégie Codexia:

• Suivre les versions CommonMark.
• Suivre la spec GFM pour compatibilité GitHub.
• Documenter tout ajout ou changement dans CHANGELOG.md.

Statut: En vigueur