Que fait Rédaction Markdown et Mermaid ?
📖 Présentation
Cette compétence vous enseigne — et impose un standard pour — la création de documentation scientifique en utilisant Markdown avec diagrammes Mermaid intégrés comme format canonique par défaut.
Le principe fondamental : une relation exprimée sous forme de diagramme Mermaid dans un fichier .md a plus de valeur
que n'importe quelle image. C'est du texte, donc il se diffère proprement dans Git. Il ne nécessite aucune étape de build.
Il se rend nativement sur GitHub, GitLab, Notion, VS Code et tout visualiseur Markdown. Il utilise
moins de tokens qu'une description textuelle de la même relation. Et il peut toujours être
converti en une image soignée plus tard — mais la version texte reste la source de vérité.
« Plus vous mettez vos rapports et fichiers en .md en texte brut, ce que Mermaid est aussi en tant que 'langage de script' simple, mieux c'est. Cela facilite tout rendu en aval et surtout les images générées par IA (utiliser Mermaid plutôt que du texte long pour décrire des relations < tokens). De plus, Mermaid peut être rendu avec Markdown pour une utilisation facile presque partout, par les humains ou l'IA. »
— Clayton Young (@borealBytes), Discord K-Dense, 2026-02-19
🎯 Quand utiliser cette compétence
Utilisez cette compétence quand :
- Vous créez un document scientifique — rapports, analyses, manuscrits, sections de méthodes
- Vous rédigez une documentation — README, tutoriels, enregistrements de décisions, documentation de projet
- Vous produisez un diagramme — workflows, pipelines de données, architectures, chronologies, relations
- Vous générez une sortie qui sera versionnée — si elle va dans Git, elle doit être en Markdown
- Vous travaillez avec une autre compétence — cette compétence définit la couche de documentation qui enveloppe toute autre sortie
- On vous demande « ajoutez un diagramme » ou « visualisez la relation » — Mermaid d'abord, toujours
NE PAS commencer par Python matplotlib, seaborn ou la génération d'images IA pour les diagrammes structurels ou relationnels. Ce sont les phases 2 et 3 — utilisées uniquement quand Mermaid ne peut pas exprimer ce qui est nécessaire (par exemple, nuages de points avec données réelles, images photoréalistes).
🎨 La philosophie du format source
Pourquoi les diagrammes textuels gagnent
| Ce qui compte | Mermaid dans Markdown | Python / Image IA |
|---|---|---|
| Diff lisible dans Git | ✅ | ❌ blob binaire |
| Modifiable sans régénération | ✅ | ❌ |
| Efficace en tokens vs. prose | ✅ plus petit | ❌ plus grand |
| Rendu sans étape de build | ✅ | ❌ nécessite hébergement |
| Analyse par IA sans vision | ✅ | ❌ |
| Fonctionne dans GitHub/GitLab/Notion | ✅ | ⚠️ si hébergé |
| Accessible (lecteurs d'écran) | ✅ accTitle/accDescr | ⚠️ nécessite texte alternatif |
| Convertible en image plus tard | ✅ à tout moment | — déjà une image |
Le workflow en trois phases
flowchart LR
accTitle: Workflow de documentation en trois phases
accDescr: La phase 1 Mermaid dans le Markdown est toujours obligatoire et est la source de vérité. Les phases 2 et 3 sont des conversions aval optionnelles pour une sortie soignée.
p1["📄 Phase 1<br/>Mermaid dans Markdown<br/>(TOUJOURS — source de vérité)"]
p2["🐍 Phase 2<br/>Généré par Python<br/>(optionnel — graphiques de données)"]
p3["🎨 Phase 3<br/>Visuels générés par IA<br/>(optionnel — polissage)"]
out["📊 Livrable final"]
p1 --> out
p1 -.->|"si nécessaire"| p2
p1 -.->|"si nécessaire"| p3
p2 --> out
p3 --> out
classDef required fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f
classDef optional fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
class p1 required
class p2,p3 optional
class out output
La phase 1 est obligatoire. Même si vous passez aux phases 2 ou 3, la source Mermaid reste engagée (commit).
Ce que Mermaid peut exprimer
Mermaid couvre 24 types de diagrammes. Presque toute relation scientifique en trouve un :
| Cas d'utilisation | Type de diagramme | Fichier |
|---|---|---|
| Workflow expérimental / logique de décision | Flowchart | references/diagrams/flowchart.md |
| Interactions de services / appels API / messagerie | Sequence | references/diagrams/sequence.md |
| Modèle de données / schéma | Diagramme ER | references/diagrams/er.md |
| Machine d'état / cycle de vie | State | references/diagrams/state.md |
| Chronologie de projet / feuille de route | Gantt | references/diagrams/gantt.md |
| Proportions / composition | Pie | references/diagrams/pie.md |
| Architecture système (niveaux de zoom) | C4 | references/diagrams/c4.md |
| Hiérarchie de concepts / remue-méninges | Mindmap | references/diagrams/mindmap.md |
| Événements chronologiques / historique | Timeline | references/diagrams/timeline.md |
| Hiérarchie de classes / relations de types | Class | references/diagrams/class.md |
| Parcours utilisateur / carte de satisfaction | User Journey | references/diagrams/user_journey.md |
| Comparaison sur deux axes / priorisation | Quadrant | references/diagrams/quadrant.md |
| Traçabilité des exigences | Requirement | references/diagrams/requirement.md |
| Magnitude de flux / distribution de ressources | Sankey | references/diagrams/sankey.md |
| Tendances numériques / graphiques à barres + lignes | XY Chart | references/diagrams/xy_chart.md |
| Disposition des composants / disposition spatiale | Block | references/diagrams/block.md |
| Statut d'élément de travail / colonnes de tâches | Kanban | references/diagrams/kanban.md |
| Infrastructure cloud / topologie de services | Architecture | references/diagrams/architecture.md |
| Comparaison multidimensionnelle / radar de compétences | Radar | references/diagrams/radar.md |
| Proportions hiérarchiques / budget | Treemap | references/diagrams/treemap.md |
| Protocole binaire / format de données | Packet | references/diagrams/packet.md |
| Branchement Git / stratégie de fusion | Git Graph | references/diagrams/git_graph.md |
| Séquence de style de code (syntaxe de programmation) | ZenUML | references/diagrams/zenuml.md |
| Modèles de composition multi-diagrammes | Exemples complexes | references/diagrams/complex_examples.md |
💡 Choisissez le bon type, pas le plus facile. Ne vous rabattez pas sur les flowcharts pour tout. Un timeline est meilleur qu'un flowchart pour les événements chronologiques. Un séquence est meilleur qu'un flowchart pour les interactions de services. Parcourez le tableau et faites correspondre.
🔧 Workflow de base
Étape 1 : Identifier le type de document
Vérifiez si un modèle existe avant d'écrire à partir de zéro :
| Type de document | Modèle |
|---|---|
| Enregistrement de pull request | templates/pull_request.md |
| Problème / bug / demande de fonctionnalité | templates/issue.md |
| Sprint / tableau de projet | templates/kanban.md |
| Décision d'architecture (ADR) | templates/decision_record.md |
| Présentation / briefing | templates/presentation.md |
| Article de recherche / analyse | templates/research_paper.md |
| Documentation de projet | templates/project_documentation.md |
| Tutoriel / guide pratique | templates/how_to_guide.md |
| Rapport de statut | templates/status_report.md |
Étape 2 : Lire le guide de style
Avant d'écrire un fichier .md : lisez references/markdown_style_guide.md.
Règles clés à internaliser :
- Un seul H1 par document — le titre. Jamais plus.
- Émoji sur les titres H2 uniquement — un émoji par H2, aucun dans H3/H4
- Citez tout — chaque affirmation externe obtient une note de bas de page
[^N]avec l'URL complète - Gras avec parcimonie — maximum 2-3 termes en gras par paragraphe, jamais des phrases complètes
- Règle horizontale après chaque
</details>— obligatoire - Tableaux plutôt que prose pour les comparaisons, configurations, données structurées
- Diagrammes plutôt que murs de texte — si cela décrit un flux, une structure ou des relations, ajoutez Mermaid
Étape 3 : Choisir le type de diagramme et lire son guide
Avant de créer un diagramme Mermaid : lisez references/mermaid_style_guide.md.
Ouvrez ensuite le fichier spécifique au type (par exemple, references/diagrams/flowchart.md) pour l'exemple, les conseils et le modèle copier-coller.
Règles obligatoires pour chaque diagramme :
accTitle: Nom court 3-8 mots
accDescr: Une ou deux phrases expliquant ce que montre ce diagramme.
- Pas de directives
%%{init}— casse le mode sombre GitHub - Pas de
styleen ligne — utilisezclassDefuniquement - Un émoji par nœud maximum — au début du libellé
- ID de nœuds en
snake_case— doit correspondre au libellé
Étape 4 : Rédiger le document
Partez du modèle. Appliquez le guide de style Markdown. Placez les diagrammes en ligne avec le texte associé — pas dans une section « Figures » séparée.
Étape 5 : Engager (commit) en texte
Le fichier .md avec Mermaid intégré est ce qui est engagé. Si vous avez également généré un PNG ou une image IA, ceux-ci sont supplémentaires — le Markdown est la source.
⚠️ Pièges courants
Syntaxe du diagramme radar (radar-beta)
MAUVAIS :
radar
title Exemple
x-axis ["A", "B", "C"]
"Série" : [1, 2, 3]
CORRECT :
radar-beta
title Exemple
axis a["A"], b["B"], c["C"]
curve série["Série"]{1, 2, 3}
max 3
- Utilisez
radar-betapasradar(le mot-clé nu n'existe pas) - Utilisez
axispour définir les dimensions, pasx-axis - Utilisez
curvepour définir les séries de données, pas les libellés entre guillemets avec deux-points - Pas de
accTitle/accDescr— radar-beta ne prend pas en charge les annotations d'accessibilité ; ajoutez toujours un paragraphe descriptif en italique au-dessus du diagramme
Confusion entre XY Chart et Radar
| Diagramme | Mot-clé | Syntaxe d'axe | Syntaxe de données |
|---|---|---|---|
| XY Chart (barres/lignes) | xychart-beta | x-axis ["Libellé1", "Libellé2"] | bar [10, 20] ou line [10, 20] |
| Radar (araignée/toile) | radar-beta | axis id["Libellé"] | curve id["Libellé"]{10, 20} |
Oubli de accTitle/accDescr sur les types pris en charge
Seuls certains types de diagrammes prennent en charge accTitle/accDescr. Pour ceux qui ne le font pas, placez toujours un paragraphe descriptif en italique directement au-dessus du bloc de code :
Diagramme radar comparant trois méthodes sur cinq dimensions de performance. Note : Les diagrammes radar ne prennent pas en charge accTitle/accDescr.
radar-beta
...
🔗 Intégration avec d'autres compétences
Avec scientific-schematics
scientific-schematics génère des images de qualité publication (PNG) alimentées par IA. Utilisez le diagramme Mermaid comme brief pour le schéma :
Workflow :
1. Créez le concept en Mermaid dans .md (cette compétence — Phase 1)
2. Décrivez le même concept à scientific-schematics pour un PNG soigné (Phase 3)
3. Engagez les deux — le .md comme source, le PNG comme figure supplémentaire
Avec scientific-writing
Quand scientific-writing produit un manuscrit, tous les diagrammes et figures structurels doivent utiliser les normes de cette compétence. La compétence d'écriture gère la prose et les citations ; cette compétence gère la structure visuelle.
Workflow :
1. Utilisez scientific-writing pour rédiger le manuscrit
2. Pour chaque figure qui montre un workflow, une architecture ou une relation :
- Remplacez l'espace réservé par un diagramme Mermaid suivant le guide de cette compétence
3. Utilisez scientific-schematics uniquement pour les figures qui nécessitent vraiment un rendu photoréaliste/complexe
Avec literature-review
La revue de littérature produit des résumés avec beaucoup de données relationnelles. Utilisez cette compétence pour :
- Créer des cartes conceptuelles (Mindmap) du paysage de la littérature
- Afficher des chronologies de publication (Timeline ou Gantt)
- Comparer des méthodologies (Quadrant ou Radar)
- Schématiser les flux de données décrits dans les articles (Sequence ou Flowchart)
Avec toute compétence produisant des documents de sortie
Avant de finaliser un document provenant d'une compétence, appliquez la liste de contrôle de cette compétence :
- Le document utilise-t-il un modèle ? Si oui, ai-je commencé par le bon ?
- Tous les diagrammes sont-ils en Mermaid avec
accTitle+accDescr? - Pas de
%%{init}, pas destyleen ligne, uniquementclassDef? - Toutes les affirmations externes sont-elles citées avec
[^N]? - Un seul H1, émoji sur H2 uniquement ?
- Règles horizontales après chaque
</details>?
📚 Index de référence
Guides de style
| Guide | Chemin | Lignes | Ce qu'il couvre |
|---|---|---|---|
| Guide de style Markdown | references/markdown_style_guide.md | ~733 | Titres, formatage, citations, tableaux, intégration Mermaid, modèles, liste de contrôle qualité |
| Guide de style Mermaid | references/mermaid_style_guide.md | ~458 | Accessibilité, jeu d'emojis, classes de couleurs, neutralité de thème, sélection de type, niveaux de complexité |
Guides de types de diagrammes (24 types)
Chaque fichier contient : un exemple de qualité production, des conseils spécifiques à ce type, et un modèle copier-coller.
references/diagrams/ — architecture, block, c4, class, complex_examples, er, flowchart, gantt, git_graph, kanban, mindmap, packet, pie, quadrant, radar, requirement, sankey, sequence, state, timeline, treemap, user_journey, xy_chart, zenuml
Modèles de documents (9 types)
templates/ — decision_record, how_to_guide, issue, kanban, presentation, project_documentation, pull_request, research_paper, status_report
Exemples
assets/examples/example-research-report.md — un rapport de recherche scientifique complet démontrant une hiérarchie de titres appropriée, plusieurs types de diagrammes (flowchart, séquence, gantt), des tableaux, des citations en notes de bas de page, des sections pliables, et toutes les règles du guide de style appliquées.
📝 Attribution
Tous les guides de style, guides de types de diagrammes et modèles de documents de cette compétence sont importés du dépôt SuperiorByteWorks-LLC/agent-project sous la licence Apache-2.0.
- Source : https://github.com/SuperiorByteWorks-LLC/agent-project
- Auteur : Clayton Young / Superior Byte Works, LLC (@borealBytes)
- Licence : Apache-2.0
Cette compétence (dans le cadre de scientific-agent-skills) est distribuée sous la licence MIT. Le contenu inclus sous licence Apache-2.0 est compatible pour une utilisation en aval, avec attribution conservée, comme préservé dans les en-têtes de fichiers tout au long de cette compétence.