Markdown

Qu'est-ce que Markdown ?

Markdown est un langage de balisage léger : on écrit du texte brut avec quelques signes de ponctuation, comme # pour un titre ou * pour l'emphase, et un convertisseur le transforme en HTML. John Gruber l'a publié en 2004 avec l'aide d'Aaron Swartz, avec pour but d'être aussi lisible que possible avant même la conversion. Les fichiers portent généralement l'extension .md.

Comment fonctionne Markdown

Un analyseur lit le texte et produit du HTML. La même source peut alimenter une page web, un README ou un site de documentation.

• # Titre devient un titre, davantage de # donnent des niveaux inférieurs.
• **gras** et *italique* marquent l'emphase.
• - élément ouvre une liste à puces, 1. élément une liste numérotée.
• [texte](https://example.com) crée un lien, ![alt](image.png) une image.
• Les accents graves encadrent le code en ligne, et trois accents graves délimitent un bloc de code.

Variantes et spécification

La description d'origine de Gruber laissait beaucoup de cas ouverts, comme l'indentation d'une sous-liste, si bien que les implémentations affichaient le même fichier différemment. La spécification CommonMark (version 0.31.2, janvier 2024) fixe la syntaxe sans ambiguïté et contient des exemples qui servent de tests. GitHub Flavored Markdown est un sur-ensemble strict de CommonMark qui ajoute les tableaux, les listes de tâches, le texte barré et des liens automatiques étendus. Vérifiez donc quelle variante votre outil utilise.

Exemple

Un README de projet peut commencer par # Payments API, une courte description, une liste de points d'accès et un bloc de code avec une requête d'exemple. Dans un dépôt, il s'affiche comme une page mise en forme. Dans un générateur de site statique (voir la génération de sites statiques), le même fichier devient une page web à la compilation.

Erreurs courantes

• Oublier la ligne vide avant une liste ou un titre, que beaucoup d'analyseurs exigent.
• Utiliser un tableau ou une liste de tâches en supposant que tous les moteurs de rendu les gèrent.
• Sauter des niveaux de titre, ce qui nuit au plan et à l'accessibilité.
• Intégrer du Markdown non fiable sans assainir le HTML produit.
• Employer Markdown pour une mise en page qu'il ne sait pas exprimer, là où le texte enrichi ou le HTML conviennent mieux.

Markdown dans la documentation et les tests

Les équipes gardent documentation, journaux des modifications et plans de test en Markdown à côté du code, pour qu'ils passent par la même relecture et la même CI. Les éléments réutilisables s'apparentent à un bloc de contenu. LoadFocus publie ses guides produit dans la documentation. Pour des pipelines qui lancent des vérifications à chaque commit, voir le guide de GitHub Actions (en anglais).

Questions fréquentes sur Markdown

À quoi sert Markdown ?

À écrire des README, de la documentation, des articles de blog, des notes et des messages en texte brut convertible en HTML. Il plaît parce que la source reste lisible et s'accorde bien avec la gestion de versions.

Quelle différence entre Markdown et HTML ?

HTML décrit une page avec des balises et couvre tout le web. Markdown est une syntaxe plus courte pour les structures courantes (titres, listes, liens) et se convertit en HTML. On peut souvent y mêler du HTML brut.

Qu'est-ce que CommonMark ?

Une spécification qui définit la syntaxe de Markdown sans ambiguïté, avec des exemples qui servent de tests de conformité. Elle est née parce que la description d'origine laissait de nombreux cas indéfinis.

Qu'est-ce que GitHub Flavored Markdown ?

GitHub Flavored Markdown (GFM) est un sur-ensemble strict de CommonMark. Il ajoute les tableaux, les listes de tâches, le texte barré et des liens automatiques étendus.

Comment convertir du Markdown en HTML ?

Avec un analyseur Markdown ou un outil qui en intègre un : générateur de site statique, aperçu d'éditeur ou convertisseur en ligne de commande. Assainissez la sortie si le Markdown vient d'utilisateurs.