En bref
JSON, YAML et Markdown sont trois formats en texte brut que vous croisez sans cesse en construisant. JSON et YAML stockent tous deux des données structurées comme des réglages et des listes, tandis que Markdown sert au texte mis en forme comme la documentation et les notes. Aucun n'est un langage de programmation ; ce sont juste des façons convenues d'écrire l'information pour que les humains comme les programmes puissent la lire. Une fois que vous reconnaissez les trois, la plupart des fichiers de config cessent de paraître effrayants.
JSON : des données pour les machines
JSON (JavaScript Object Notation) stocke des données sous forme de paires clé-valeur, avec des accolades et des guillemets. On le trouve partout : réponses d'API, fichiers de paquets, réglages d'applications. Il est strict, donc une seule virgule ou un guillemet manquant le casse.
{
"name": "my-app",
"version": "1.0.0",
"private": true
}YAML : des données pour les humains
YAML stocke le même type de données que JSON, mais utilise l'indentation au lieu des accolades, ce qui le rend plus facile à lire et à écrire à la main. On le trouve souvent dans les configs de workflow et de déploiement. Le piège : les espaces comptent. YAML utilise des espaces pour l'indentation, jamais de tabulations.
name: my-app
version: 1.0.0
private: trueMarkdown : de l'écriture mise en forme
Markdown est pour le texte, pas pour les données. Vous ajoutez de simples symboles à du texte brut pour marquer titres, gras, listes et liens, et il s'affiche comme du contenu joliment mis en forme. Cette page, la plupart des README et les fichiers d'instructions IA comme CLAUDE.md sont tous en Markdown.
# Un titre
Un peu de texte **en gras** et une liste :
- premier élément
- deuxième élémentComment les distinguer
Une règle rapide dissipe l'essentiel de la confusion. Si vous voyez des accolades et beaucoup de guillemets, c'est du JSON. Si vous voyez une indentation propre avec des deux-points et sans accolades, c'est du YAML. Si vous voyez des titres "#" et des puces "-" destinés à un humain, c'est du Markdown. Vous n'avez à écrire aucun d'eux parfaitement à la main, car votre agent IA génère et modifie ces fichiers pour vous. Il aide de reconnaître ce qui est quoi, pour que lorsqu'un outil réclame "une config YAML" ou "un fichier JSON", vous sachiez ce qu'il attend et repériez une erreur évidente d'un coup d'oeil.