1. Qu'est-ce que le Markdown : philosophie, CommonMark et pourquoi c'est la langue maternelle de l'IA
Markdown est un langage de balisage léger pour le texte, créé par John Gruber en 2004 avec un objectif simple : écrire du texte structuré qui reste extrêmement lisible à l'état brut et se convertit facilement en HTML valide. La référence actuelle du format est standardisée dans la spécification CommonMark et étendue par la norme GitHub Flavored Markdown (GFM).
Dans l'interaction avec l'intelligence artificielle (ChatGPT, Claude Code, Gemini, modèles locaux Ollama), le Markdown est précisément la langue principale de communication.
Pourquoi les grands modèles de langage « pensent » en Markdown
- Économie optimale de tokens : Contrairement au XML ou au HTML, où chaque balise nécessite une ouverture et une fermeture (
<p>Texte</p>), le Markdown utilise uniquement des marqueurs de service minimaux ou des sauts de ligne simples. - Univocité sémantique : Les symboles
#,-,>et les backticks de code ne surchargent pas la fenêtre contextuelle, offrant au modèle une carte claire de la hiérarchie des idées. - Naturel pour la sortie en streaming : La génération de texte mot par mot sans balises complexes non fermées permet de rendre le formatage à la volée dans l'interface de chat.
- Contrôle de version dans Git : Les fichiers
.mdsont de simples fichiers texte, ce qui signifie que toute modification dans la base de connaissances ou la documentation est facilement traçable viagit diff.
Le formatage en Markdown se divise en deux niveaux : éléments de bloc (titres, listes, citations, tableaux, blocs de code) et éléments inline (gras, italique, liens, code inline). Les éléments de bloc doivent impérativement être séparés par une ligne vide.
2. Hiérarchie des titres et structure de navigation des documents
Les titres définissent la colonne vertébrale du document et génèrent la table des matières (Table of Contents). En Markdown, les niveaux de titre sont indiqués par le symbole dièse (#) au début de la ligne — de un à six.
Hiérarchie des niveaux de titres en Markdown et balises HTML correspondantes| Niveau de titre | Syntaxe Markdown | Équivalent HTML | Utilisation typique |
|---|---|---|---|
| Niveau 1 | # Titre | <h1> | Nom de l'article ou du document entier (un seul par page) |
| Niveau 2 | ## Titre | <h2> | Sections principales et modules clés du sujet |
| Niveau 3 | ### Titre | <h3> | Sous-sections, étapes d'instructions, outils spécifiques |
| Niveau 4 | #### Titre | <h4> | Détails des sous-points, paramètres, notes |
| Niveau 5 | ##### Titre | <h5> | Petites notes de bas de page techniques |
| Niveau 6 | ###### Titre | <h6> | Micro-titres de spécifications |
Règle critique de l'espace après le dièse
Conformément à la norme CommonMark, il doit y avoir impérativement un espace unique entre le symbole dièse et le texte du titre. Si l'espace est absent, la plupart des parsers modernes interpréteront l'entrée comme un hashtag ordinaire ou du texte brut.
Comparaison de l'écriture correcte et incorrecte des titresN'utilisez jamais le symbole # pour un titre de premier niveau à l'intérieur du corps de l'article si le titre est déjà défini dans les métadonnées (frontmatter). Il doit y avoir exactement une balise sémantique <h1> sur la page.
3. Mise en forme du texte : gras, italique, barré et caractères spéciaux
La mise en évidence inline aide à attirer l'attention sur les termes et concepts clés.
Syntaxe de mise en italique du texte en Markdown| Style de mise en évidence | Syntaxe Markdown | Résultat affiché |
|---|---|---|
| Gras (Bold) | **terme important** ou __terme__ | terme important |
| Italique (Italic) | *accent* ou _accent_ | accent |
| Gras italique | ***action critique*** | action critique |
| Barré (Strikethrough) | ~~version obsolète~~ | |
| Code inline | `apiKey` | apiKey |
Nuances pratiques de typographie
- Mise en évidence à l'intérieur d'un mot : Pour mettre en évidence une partie d'un mot, utilisez toujours les astérisques (
A*cat*meow), car certains processeurs ignorent le soulignement à l'intérieur des mots, le percevant comme faisant partie d'un identifiant de variable (user_profile_id). - Saut de ligne sans nouveau paragraphe : Pour ajouter un saut de ligne (
<br>) à l'intérieur d'un même paragraphe, placez deux espaces à la fin de la ligne ou utilisez la balise<br>. - Commentaires : Pour les notes qui ne doivent pas être rendues sur la page finale, utilisez la syntaxe des commentaires HTML :
<!-- Ceci est un commentaire interne -->.
4. Listes et structures imbriquées : numérotées, à puces et cases à cocher
Les listes structurent les algorithmes étape par étape et les ensembles de paramètres.
Listes à puces et numérotées
Blocs supplémentaires à l'intérieur des listes
Pour insérer un paragraphe, une citation ou un bloc de code à l'intérieur d'un point de liste sans rompre la numérotation générale, effectuez une indentation de 4 espaces avant chaque ligne enfant :
Assurez-vous que les variables d'environnement dans le fichier .env sont correctement configurées avant le lancement.
- Vérifiez le répertoire de sortie
dist/.
6. Code inline, blocs de code et coloration syntaxique
Le code et les configurations nécessitent une police monospace et une protection contre l'interprétation des caractères internes.
Code inline vs Blocs de code Fenced
- Code inline : guillemets inversés simples (backticks) :
git status. - Échappement d'un backtick dans du code inline : enveloppement avec double backticks :
`npm test`. - Blocs de code Fenced : triple backticks avec indication obligatoire de l'identifiant du langage.
Règle stricte d'isolation des prompts : Tout prompt système ou règle d'assistant (.cursorrules, CLAUDE.md) contenant ses propres symboles de titre (#, ##) doit impérativement être enveloppé dans un bloc de code distinct avec indication du langage (par exemple, markdown ou text). S'ils sont laissés sans bloc de code dans le corps du texte, les titres internes du prompt apparaîtront dans la table des matières (TOC) de l'article et briseront la navigation de la page.
7. Citations, callouts et séparateurs horizontaux
Les citations sont créées avec le symbole > au début de la ligne et sont utilisées pour mettre en évidence des réflexions, des avertissements importants ou des citations de texte.
Citations standard et imbrication multi-niveaux
Alertes GitHub modernes (blocs Callout)
Les plateformes de documentation modernes prennent en charge des blocs mis en évidence standardisés avec des icônes colorées :
Séparateurs horizontaux
Trois tirets ou plus (---), astérisques (***) ou soulignés (___) sur une ligne séparée créent une ligne horizontale :
8. Échappement des caractères spéciaux et HTML intégré
Lorsqu'il faut afficher un caractère de syntaxe Markdown comme un signe typographique ordinaire, on place une barre oblique inverse (\) devant lui.
Caractères spéciaux de la syntaxe Markdown pouvant être échappés avec une barre oblique inverseListe des caractères à échapper
| Caractère | Nom du signe | Exemple d'échappement | Résultat du rendu |
|---|---|---|---|
\ | Barre oblique inverse (Backslash) | \\ | \ |
` | Guillemet inversé (Backtick) | \` | ` |
* | Astérisque (Asterisk) | \*pas italique\* | *pas italique* |
_ | Souligné (Underscore) | \_pas gras\_ | _pas gras_ |
# | Dièse (Hash) | \# Pas un titre | # Pas un titre |
[ ] | Crochets | \[Pas un lien\] | [Pas un lien] |
! | Point d'exclamation | \!Pas une image | !Pas une image |
Utilisation sécurisée du HTML
Si le Markdown standard est insuffisant, vous pouvez utiliser des balises HTML, mais gardez à l'esprit les limitations :
- La balise
<br>pour les sauts de ligne forcés dans les tableaux. - La balise
<u>pour le texte souligné. - Les balises de bloc (
<div>,<table>) doivent être séparées du code Markdown par des lignes vides, et le balisage Markdown ne fonctionne pas à l'intérieur d'elles.
9. Tableaux GitHub Flavored Markdown (GFM) et diagrammes Mermaid
Les tableaux permettent de comparer des caractéristiques, des paramètres et des configurations.
Syntaxe des tableaux GFM avec alignement
:---— alignement de la colonne à gauche.:---:— alignement centré.---:— alignement à droite (idéal pour les prix et les nombres).
Visualisation de l'architecture via Mermaid
Au lieu de captures d'écran raster lourdes, les développeurs modernes utilisent des diagrammes textuels intégrés Mermaid :
10. Markdown dans les agents IA : CLAUDE.md, System Prompts et checklist de validation
À l'ère des agents IA autonomes (Claude Code, Cursor, Windsurf, Devin), le Markdown est devenu la langue principale de transmission du contexte d'ingénierie.
Fichiers d'instructions du projet (CLAUDE.md / .cursorrules)
Les agents lisent le fichier racine CLAUDE.md avant chaque requête. S'il est bien formaté, le modèle suit sans erreur l'architecture du projet :
Prompt maître pour générer du Markdown impeccable
Checklist de contrôle qualité du document Markdown
- Aucun tag
#(H1) n'est présent dans le corps de l'article (le H1 est généré exclusivement à partir du titre de la page). - Toutes les sections de premier niveau sont numérotées séquentiellement (
## 1.,## 2.). - Un espace suit obligatoirement les symboles dièse
#. - Tous les prompts, configurations et exemples de code sont enveloppés dans des blocs
```appropriés. - Les caractères spéciaux dans les liens sont encodés au format percent-encoding.
- Les tableaux sont formatés selon la norme GFM sans séparateurs corrompus.