Guide de la syntaxe étendue markdown : tableaux, notes de bas de page, listes de tâches et plus

La syntaxe étendue markdown regroupe les éléments de mise en forme ajoutés après la publication de la spécification originale par John Gruber en 2004. La spécification de 2004 définissait 11 éléments de base et laissait totalement de côté les tableaux, les notes de bas de page, les listes de tâches et le texte barré. Des projets ultérieurs ont comblé ces lacunes : MultiMarkdown a apporté les tableaux et les notes de bas de page en 2005, Pandoc est arrivé en 2006 avec le plus grand ensemble d'extensions de tous les processeurs, CommonMark a standardisé le cœur du langage en 2014 en prévoyant la place pour des extensions, et GitHub a publié la spécification GFM en 2017. Chaque élément de cette page s'affiche dans l'aperçu en direct de l'éditeur : un collage de 5 secondes vous indique donc si votre application cible le prend en charge.

Tableau de compatibilité

Aucune application ne prend en charge les 12 éléments étendus, alors vérifiez la compatibilité de votre destination avant de publier. Les 4 destinations les plus courantes diffèrent nettement :

Un raccourci pratique : les tableaux, les blocs de code délimités, le texte barré et les listes de tâches s'affichent presque partout. Les listes de définitions, le surlignage, l'indice et l'exposant sont les 4 éléments qui risquent le plus d'échouer.

Tableaux

Un tableau markdown sépare les colonnes par des barres verticales et marque la ligne d'en-tête avec une ligne de séparation de 3 tirets ou plus. Les barres extérieures sont facultatives dans la plupart des parseurs, mais elles améliorent la compatibilité, alors conservez-les.

| Feature | Status |
| :------ | -----: |
| Export  | Done   |
| Sync    | Open   |

Les deux-points dans la ligne de séparation contrôlent l'alignement. :--- aligne une colonne à gauche, :---: la centre et ---: la pousse à droite. Le parseur applique l'alignement à chaque cellule de la colonne. Le nombre de tirets n'a pas besoin d'être identique d'une colonne à l'autre. Pour afficher une barre verticale littérale dans une cellule, écrivez l'entité HTML | ; GitHub accepte aussi l'échappement par barre oblique inverse \|. Les cellules acceptent la mise en forme en ligne, comme le gras et les portions de code, mais jamais les éléments de bloc comme les listes ou les titres.

MultiMarkdown a introduit cette syntaxe en 2005 et GFM l'a adoptée en 2017. GitHub, GitLab, Obsidian et Pandoc affichent les tableaux. Discord ne le fait pas.

Blocs de code délimités

Un bloc de code délimité s'ouvre et se ferme avec 3 accents graves et ne demande aucune indentation, contrairement aux blocs de code à 4 espaces de la spécification de 2004. Trois tildes fonctionnent comme délimiteur alternatif dans la plupart des parseurs.

```python
def total(items):
    return sum(items)
```

Un identifiant de langage placé juste après le délimiteur d'ouverture active la coloration syntaxique. highlight.js, la bibliothèque derrière de nombreux moteurs de rendu web, fournit des définitions pour environ 200 langages, et les identifiants courants incluent python, js, json, bash et sql. Pour afficher un bloc de code à l'intérieur d'un autre bloc de code, passez le délimiteur extérieur à 4 accents graves.

La prise en charge est la plus large de tous les éléments étendus. GitHub, Obsidian, Discord et Pandoc affichent tous les blocs délimités, et les 4 appliquent la coloration syntaxique.

Notes de bas de page

Une note de bas de page markdown comporte 2 parties : un marqueur de référence dans le corps du texte, écrit [^1], et une définition placée n'importe où dans le fichier, écrite [^1]: suivie de la note. Le moteur de rendu rassemble toutes les définitions en bas de la page et relie chaque paire dans les deux sens.

The claim has a published source.[^1]

[^1]: Smith, 2024, p. 41.

Les identifiants peuvent être des mots aussi bien que des nombres, et [^note] se comporte exactement comme [^1], car la numérotation en sortie suit l'ordre du document plutôt que l'étiquette. Une note de bas de page peut contenir plusieurs paragraphes lorsque les paragraphes supplémentaires sont indentés de 4 espaces sous la définition.

MultiMarkdown a livré les notes de bas de page en 2005, Pandoc et Obsidian les prennent en charge intégralement, et GitHub a ajouté leur rendu en 2021. Discord n'offre aucune prise en charge des notes de bas de page.

Identifiants de titres

Un identifiant de titre personnalisé se place entre accolades à la fin de la ligne de titre, et ## Refund Policy {#refunds} produit l'élément HTML h2 avec id="refunds". L'identifiant devient une ancre stable pour les liens et le CSS.

## Refund Policy {#refunds}

Jump straight to [the refund policy](#refunds).

Le lien est un lien markdown standard avec un croisillon et l'identifiant comme cible. Les pages externes atteignent le même endroit lorsque #refunds est ajouté à l'URL complète de la page.

Pandoc et PHP Markdown Extra interprètent la forme entre accolades. GitHub l'ignore, mais génère des identifiants automatiques à partir du texte des titres, donc un lien vers #refund-policy y fonctionne quand même. Obsidian utilise son propre motif [[Note#Heading]] pour les liens vers les titres. Discord affiche les titres dans les messages, mais ne dispose d'aucun système d'ancres.

Listes de définitions

Une liste de définitions associe un terme à 1 ou plusieurs définitions : le terme occupe seul une ligne, et chaque définition commence à la ligne suivante par un deux-points et une espace.

Markdown
: A plain-text formatting syntax released in 2004.

Parser
: Software that converts markdown into HTML.
: Also called a processor.

Le résultat est un véritable élément <dl> avec des enfants <dt> et <dd>, ce qui compte pour les glossaires et pour les lecteurs d'écran. Des lignes de deux-points empilées donnent plusieurs définitions à un même terme.

La prise en charge est étroite. PHP Markdown Extra a défini la syntaxe, et Pandoc comme MultiMarkdown l'interprètent. GitHub et Obsidian affichent les lignes de deux-points comme du texte brut, et Discord fait de même. Le HTML brut <dl> reste la solution de repli fiable sur GitHub.

Texte barré

Le texte barré entoure le texte de 2 tildes de chaque côté, si bien que like this s'affiche comme du texte rayé. L'élément vient de GFM, et la sortie HTML est un élément <del>.

~~Ship v2 on Friday.~~ Moved to Monday.

GitHub accepte aussi un seul tilde de chaque côté. Restez à 2 pour la portabilité, car un tilde simple signifie indice dans Pandoc et une différence d'un seul caractère inverse le sens.

La prise en charge est quasi universelle. GitHub, Obsidian, Discord et Pandoc affichent tous le texte barré à 2 tildes.

Listes de tâches

Un élément de liste de tâches markdown commence comme un élément de liste normal et ajoute des crochets : - [ ] marque une tâche ouverte et - [x] marque une tâche terminée. L'espace à l'intérieur des crochets vides est obligatoire.

- [x] Draft the outline
- [x] Write the copy
- [ ] Publish the page

GitHub a introduit la syntaxe en 2013 et a rendu les cases à cocher interactives dans les issues et les pull requests, où un clic met à jour le markdown sous-jacent. GitHub les compte aussi, si bien qu'une issue affiche une progression telle que « 2 of 3 tasks ». Obsidian affiche des cases cliquables en mode lecture, et Pandoc convertit les listes de tâches en cases à cocher HTML. Discord laisse les crochets tels quels.

Émojis

Les émojis entrent dans un fichier markdown de 2 façons : collez directement le caractère Unicode, ou tapez un code court comme :rocket: dans les applications qui développent les codes courts. Les émojis collés survivent dans tout fichier UTF-8, donc 🎯 s'affiche même là où les codes courts échouent.

Release day :tada: went live at 9 am.

Un code court entoure le nom d'un émoji de 2 deux-points. GitHub développe environ 1 800 codes courts, et Discord développe son propre jeu plus les émojis personnalisés des serveurs. Obsidian a besoin d'un plugin communautaire pour les codes courts, mais affiche nativement les émojis collés, et Pandoc ne développe les codes courts qu'avec son extension emoji activée. Les noms varient d'une plateforme à l'autre, donc un code court qui fonctionne sur GitHub n'est garanti nulle part ailleurs.

Surlignage

Le surlignage entoure le texte de 2 signes égal, et ==like this== s'affiche avec un fond de type surligneur, généralement jaune. La sortie HTML est un élément <mark>.

The deadline moved to ==14 March== at noon.

C'est l'un des éléments étendus les moins portables. Obsidian l'affiche par défaut, et Pandoc l'interprète une fois l'extension mark activée, disponible depuis Pandoc 3.0 en 2023. GitHub et Discord affichent les signes égal littéralement. Là où la syntaxe échoue, la balise <mark> fonctionne dans tout moteur de rendu qui laisse passer le HTML, ce qui inclut les fichiers readme de GitHub.

Indice et exposant

L'indice entoure les caractères de tildes simples, comme dans H2O, et l'exposant les entoure de carets simples, comme dans x^2^. Les deux formes viennent de l'ensemble d'extensions de Pandoc plutôt que d'une variante web courante.

H~2~O freezes at 0 degrees.
E = mc^2^ dates from 1905.

Pandoc les convertit en éléments <sub> et <sup>. GitHub et Obsidian ignorent les formes à tilde et à caret, mais laissent passer les balises HTML, donc H₂O fonctionne sur les deux. Discord ne prend en charge ni l'un ni l'autre. Attention à la collision de tildes : une application qui barre le texte avec un tilde simple rayera votre indice au lieu de l'abaisser.

Liens URL automatiques

Le lien URL automatique transforme une adresse nue comme https://example.com en lien cliquable sans aucune syntaxe de crochets. GFM a formalisé ce comportement sous le nom d'extension autolink dans sa spécification de 2017.

Full docs at https://example.com/docs

GitHub et Discord transforment les URL nues en liens, et Obsidian fait de même en mode lecture. Pandoc garde ce comportement désactivé tant que l'extension autolink_bare_uris n'est pas activée. Pour empêcher une URL de devenir un lien, entourez-la d'accents graves ; les portions de code ne créent jamais de liens, donc https://example.com reste du texte brut dans les exemples de configuration et les domaines fictifs.

Questions fréquentes

La syntaxe étendue fait-elle partie du markdown officiel ?

Non. La spécification de 2004 définit 11 éléments de base, et chaque élément de cette page vient de variantes et de processeurs ultérieurs. Markdown n'a pas d'organisme de gouvernance, ce qui explique pourquoi la prise en charge varie d'une application à l'autre.

Quelle variante de markdown prend en charge le plus de syntaxe étendue ?

Pandoc prend en charge l'éventail le plus large, avec plus de 30 extensions de syntaxe optionnelles, et il interprète les 12 éléments de cette page. GFM reste la cible la plus pratique pour la publication web, car GitHub, GitLab et la plupart des éditeurs modernes la suivent.

Pourquoi un tableau s'affiche-t-il sur GitHub mais pas dans Discord ?

Discord implémente un sous-ensemble markdown restreint conçu pour le chat et laisse de côté les tableaux, les notes de bas de page, les listes de tâches et les listes de définitions. Son sous-ensemble couvre le gras, l'italique, le texte barré, les titres et les blocs de code délimités. Le contenu destiné à Discord doit se limiter à ces 5 éléments.

Comment tester la syntaxe étendue avant de publier ?

Collez l'élément dans l'aperçu en direct de l'éditeur en ligne, qui affiche GFM plus les notes de bas de page en moins d'1 seconde. Pour toute autre destination, collez un échantillon de 2 lignes dans l'application cible elle-même ; le tableau de compatibilité couvre les 4 cas les plus courants.