Aide-mémoire Markdown : les 21 éléments de syntaxe sur une page
Un aide-mémoire markdown est une référence d'une seule page qui associe chaque élément markdown à sa syntaxe exacte, pour que vous puissiez mettre en forme un document sans retourner dans la documentation complète. Cette antisèche markdown couvre les 21 éléments en deux tableaux : les 10 éléments de base définis par John Gruber dans la spécification originale de 2004, et les 11 éléments étendus ajoutés ensuite par des variantes comme CommonMark (2014) et GitHub Flavored Markdown (2017). Chaque exemple de syntaxe markdown de cette page fonctionne aussi dans l'éditeur markdown en ligne, où l'aperçu en direct affiche le rendu pendant que vous tapez.
Syntaxe de base
La syntaxe de base regroupe les 10 éléments issus de la conception originale du markdown en 2004, et toutes les applications markdown les rendent à l'identique. Ces 10 éléments couvrent l'essentiel de l'écriture au quotidien : la structure vient des titres et des listes, l'accentuation vient du gras et de l'italique, et les références viennent des liens et des images. Si un document n'utilise que les lignes de ce tableau, il s'affiche correctement sur GitHub, dans Obsidian, sur Reddit, dans Discord et dans tout éditeur créé après 2004.
| Élément | Syntaxe | Résultat rendu |
|---|---|---|
| Titre | # H1 / ## H2 / ### H3 | Titres de section des niveaux 1 à 6 ; un # par niveau |
| Gras | **strong words** | mots en gras |
| Italique | *slanted words* | mots en italique |
| Citation | > quoted line | Bloc de citation en retrait avec une bordure à gauche |
| Liste ordonnée | 1. Step one 2. Step two | Liste numérotée ; la numérotation s'affiche dans l'ordre |
| Liste non ordonnée | - First point - Second point | Liste à puces ; * et + fonctionnent aussi comme marqueurs |
| Code | `inline code` | code en ligne dans un encadré à chasse fixe |
| Ligne horizontale | --- | Ligne de séparation pleine largeur entre les sections |
| Lien | [anchor text](https://example.com) | Lien hypertexte cliquable libellé "texte d'ancrage" |
| Image |  | Image intégrée avec texte alternatif pour l'accessibilité |
Le marqueur de titre exige une espace après le dernier #, et la ligne horizontale exige une ligne vide au-dessus. Ces deux détails causent la plupart des échecs de rendu en syntaxe de base.
Syntaxe étendue
La syntaxe étendue ajoute 11 éléments absents de la spécification originale de 2004, et leur prise en charge dépend de la variante markdown que l'application implémente. Les tableaux, les blocs de code délimités et les listes de tâches sont arrivés avec GitHub Flavored Markdown, que GitHub a formalisé dans une spécification en 2017. Les notes de bas de page, les listes de définitions et le surlignage viennent d'autres variantes et s'affichent dans moins d'applications.
| Élément | Syntaxe | Résultat rendu |
|---|---|---|
| Tableau | | Name | Role | | --- | --- | | Ada | Engineer | | Grille avec une ligne d'en-tête et des colonnes alignées |
| Bloc de code délimité | ```json { "id": 1 } ``` | Encadré de code multiligne avec coloration syntaxique optionnelle |
| Note de bas de page | A claim.[^1] [^1]: The source. | Renvoi numéroté avec une note en bas de page |
| ID de titre | ## Pricing {#pricing} | Titre avec une ancre personnalisée pour les liens directs |
| Liste de définitions | Term : Meaning of the term | Terme sur une ligne, définition en retrait dessous |
| Texte barré | ~~old figure~~ | |
| Liste de tâches | - [x] Ship the draft - [ ] Review edits | Liste à cocher avec cases cochées et non cochées |
| Code emoji | :tada: | Le caractère emoji correspondant, 🎉 |
| Surlignage | ==key phrase== | Phrase sur un fond coloré |
| Indice | H~2~O | H₂O |
| Exposant | x^2^ | x² |
La prise en charge varie selon l'application : GitHub rend les tableaux, les blocs de code délimités, les listes de tâches, le texte barré, les notes de bas de page et les codes emoji, mais ignore le surlignage, l'indice et l'exposant ; Obsidian gère les tableaux, les notes de bas de page, les listes de tâches, le texte barré et le surlignage ; Discord accepte le gras, l'italique, le texte barré et les blocs de code, mais ne prend en charge ni les tableaux ni les notes de bas de page. Quand la plateforme cible est inconnue, les 10 éléments de base constituent le choix sûr.
Comment utiliser cet aide-mémoire
Repérez l'élément dans la colonne de gauche, copiez la syntaxe dans la colonne du milieu, puis remplacez le texte d'exemple par votre propre contenu. La colonne du résultat rendu montre à quoi ressemble la sortie, pour que vous puissiez vérifier que l'élément correspond à votre intention avant de le copier. Pour tout élément du tableau étendu, consultez d'abord la note de compatibilité ; une note de bas de page qui s'affiche sur GitHub disparaît sur Discord.
Le moyen le plus rapide de vérifier la syntaxe markdown est de la coller dans l'éditeur markdown en ligne. L'aperçu en direct rend chaque élément en quelques millisecondes, donc un tableau cassé ou un marqueur ** non fermé apparaît immédiatement. Les personnes qui écrivent en markdown tous les jours mémorisent généralement le tableau de base en une semaine ; le tableau étendu est la partie à garder sous la main.
Télécharger et imprimer
Cet aide-mémoire tient sur une page A4 et est disponible en fichier .md, pour que vous puissiez en garder une copie dans votre application de notes ou l'imprimer pour votre bureau. Le fichier téléchargé est lui-même du markdown valide, et les deux tableaux s'affichent correctement dans toute application qui prend en charge les tableaux GFM. Ouvrez-le dans l'éditeur, dans Obsidian ou dans un dépôt GitHub et la référence reste mise en forme.
Questions fréquentes
Quelle est la différence entre la syntaxe markdown de base et la syntaxe étendue ?
La syntaxe de base désigne les 10 éléments de la spécification originale de 2004, et la syntaxe étendue désigne les 11 éléments ajoutés ensuite par les variantes. Toutes les applications markdown prennent en charge l'ensemble de base. L'ensemble étendu dépend de la variante : CommonMark a standardisé le comportement de base en 2014, et GFM a ajouté les tableaux, les listes de tâches et le texte barré dans sa spécification de 2017.
Toutes les applications markdown prennent-elles en charge la syntaxe étendue ?
Non. La prise en charge de la syntaxe étendue varie selon l'application, et aucune application ne rend les 11 éléments étendus à elle seule. GitHub ignore le surlignage et l'indice, Discord ignore les tableaux et les notes de bas de page, et Obsidian couvre la gamme la plus large des trois. Les documents destinés à plusieurs plateformes devraient s'appuyer sur la syntaxe de base plus les tableaux GFM.
Le markdown est-il difficile à apprendre ?
Non. Le markdown compte 21 éléments au total, et les 10 éléments de base couvrent la plupart des documents. Un # pour les titres, ** pour le gras et - pour les listes représentent l'essentiel de l'usage réel. La plupart des gens écrivent un markdown fluide après une seule session avec un éditeur à aperçu en direct, car l'aperçu corrige les erreurs sur-le-champ.