Le Markdown est une syntaxe incontournable pour tout développeur que l'on retrouve partout : dans les fichiers README.md sur GitHub, dans les commentaires d'issues, dans les outils de prise de note comme Obsidian ou Notion, et même dans les systèmes de commentaires de certains sites. Dans cet article on va voir ensemble ce qu'est le Markdown, sa syntaxe de base et ses extensions les plus utiles.
Création & Usage
Le Markdown a été créé par John Gruber et sa particularité réside dans le fait qu'il est lisible dans son format texte brut tout en étant convertissable en HTML (ou autre format plus avancé). C'est par exemple ce que fait GitHub lorsqu'il affiche le contenu d'un fichier README.md à la racine d'un projet : le markdown est converti en HTML pour offrir une présentation agréable.
L'avantage par rapport à des formats comme Word ou OpenOffice, c'est qu'on n'a pas besoin de logiciel particulier pour éditer un fichier Markdown. Un simple éditeur de texte suffit. Les éditeurs modernes comme Visual Studio Code offrent un support natif de cette syntaxe avec souvent aperçu en temps réel du rendu HTML.
Syntaxe de base
Pour créer son premier fichier, il suffit de créer un fichier avec l'extension .md (par exemple README.md). Ensuite, pour créer vos premier paragraphes il suffit d'écrire votre texte en séparant les paragraphes par une ligne de texte vide.
Titres
Pour créer un titre de premier niveau, on le préfixe d'un #. Pour un titre de second niveau on utilise ##, et ainsi de suite jusqu'à six niveaux.
Il existe une syntaxe alternative avec des = ou des - sous le texte, mais la syntaxe avec les # est plus pratique et plus courante.
Emphase
Pour mettre en italique, on entoure le texte d'une * ou d'un _. Pour le mettre en gras, on utilise deux étoiles.
De cette manière, même sans interprétation, le document reste lisible et on identifie facilement ce qui est important.
Listes
Pour créer une liste non ordonnée, on préfixe chaque élément d'un tiret - (on peut aussi utiliser + ou *, mais par convention on utilise le tiret).
Pour une liste ordonnée, on met le numéro suivi d'un point.
Citations
Pour citer un texte, on utilise le signe > en début de ligne.
Séparateur horizontal
Pour séparer visuellement des sections, on aligne trois tirets ou plus.
Code
Pour mettre en avant un mot-clé ou un nom de classe dans du texte, on l'entoure d'un backtick : `maClasse`.
Pour un bloc de code, on utilise trois backticks. On peut préciser le langage après les backticks d'ouverture pour activer la coloration syntaxique.
Il existe aussi une approche par référence qui fonctionne comme les notes de bas de page sur Wikipédia. On met un identifiant entre crochets à la place de l'URL, et on définit la référence en bas du document.
Cette approche permet de garder le texte lisible tout en ayant tous les liens regroupés en bas du document.
Images
Pour les images, c'est la même syntaxe que les liens, mais préfixée d'un point d'exclamation.
Syntaxe avancée
Le Markdown de base a été étendu par plusieurs acteurs, notamment GitHub avec le GitHub Flavored Markdown (GFM) qui ajoute des fonctionnalités supplémentaires.
Liens automatiques
Si on colle directement une URL dans le texte, elle sera automatiquement convertie en lien cliquable dans le rendu HTML.
Texte barré
Pour barrer du texte, on l'entoure de deux tildes.
Tableaux
On peut créer des tableaux en utilisant des pipes | pour séparer les colonnes.
C'est une syntaxe un peu plus verbeuse, mais elle permet de créer des tableaux directement en texte brut. Des outils comme StackEdit offrent des raccourcis pour les créer plus facilement.
Listes de tâches
On peut créer des listes de tâches avec des cases à cocher.
Sur des outils comme StackEdit ou GitHub, les cases sont interactives : on peut cocher directement une tâche et le Markdown source sera mis à jour.
Diagrammes avec Mermaid
Si le système qui interprète le Markdown le supporte (c'est le cas de GitHub et de StackEdit), on peut intégrer des diagrammes Mermaid. On utilise un bloc de code avec mermaid comme langage.