Apprendre le Markdown : guide débutant complet
Markdown est un langage de balisage léger créé en 2004 par John Gruber pour formater du texte de façon simple et lisible même dans sa version brute. Aujourd'hui, il est utilisé sur GitHub, Stack Overflow, Notion, Discord, Slack, Reddit et des milliers d'autres plateformes. Ce guide vous enseigne les bases du Markdown en utilisant l'Éditeur Markdown de WikiPlus comme terrain de pratique interactive.
Les bases : titres, paragraphes et sauts de ligne
Les titres en Markdown sont créés en commençant la ligne avec un ou plusieurs caractères dièse (#). Un seul # crée un titre H1 (le plus grand), ## crée un H2, ### un H3, jusqu'à ###### pour un H6. Les paragraphes sont des blocs de texte séparés par une ligne vide. Un simple retour à la ligne dans le Markdown ne crée pas un nouveau paragraphe dans le rendu HTML : il faut une ligne vide entre deux paragraphes. Pour forcer un retour à la ligne sans nouveau paragraphe, terminez la ligne par deux espaces puis appuyez sur Entrée. Cette subtilité est souvent source de confusion pour les débutants : si votre texte semble s'afficher sur une seule ligne alors que vous avez appuyé sur Entrée, c'est que vous n'avez pas laissé de ligne vide entre les paragraphes.
Formatage du texte : gras, italique, code et liens
Le formatage inline s'applique à l'intérieur d'un paragraphe. Le gras s'obtient avec **double astérisques** ou __double tiret bas__. L'italique avec *simple astérisque* ou _simple tiret bas_. Le gras italique avec ***triple astérisque***. Le code inline avec `backticks` (accent grave) : utilisé pour les commandes, les noms de fichiers et les extraits de code. Le texte barré avec ~~double tilde~~. Les liens avec [texte cliquable](https://url.com). Les liens avec texte alternatif affiché au survol avec [texte](https://url.com 'Titre du lien'). Pratiquez ces éléments dans l'Éditeur Markdown WikiPlus : tapez la syntaxe et observez le rendu en temps réel dans le panneau droit.
Listes, tableaux et blocs de code
Les listes à puces commencent par -, * ou +. Les listes numérotées commencent par 1. (le nombre réel n'a pas d'importance, Markdown les numérote automatiquement). Les listes peuvent être imbriquées en ajoutant une indentation (2 ou 4 espaces). Les tableaux GitHub Flavored Markdown s'écrivent avec des pipes (|) : | Colonne 1 | Colonne 2 | puis | --- | --- | pour les en-têtes, puis les lignes de données. Les blocs de code sont délimités par ``` (triple backtick). Pour la coloration syntaxique, ajoutez le nom du langage après les premiers backticks : ```javascript ```python ```bash. L'Éditeur WikiPlus affiche la coloration syntaxique dans le panneau de prévisualisation pour les langages populaires.
Images, citations et règles horizontales
Les images en Markdown ont la syntaxe . Le texte alternatif est affiché si l'image ne charge pas et est lu par les lecteurs d'écran. Pour les images locales dans l'éditeur WikiPlus, l'image doit être hébergée en ligne pour apparaître dans la prévisualisation (les images locales ne peuvent pas être référencées par chemin de fichier dans un éditeur de navigateur). Les citations blockquote commencent par > : elles s'affichent avec une barre verticale à gauche et un fond légèrement différent. Les règles horizontales (lignes séparatrices) s'obtiennent avec ---, ___ ou *** sur une ligne seule. Ces éléments sont très utilisés dans la documentation technique et les articles de blog pour structurer visuellement le contenu.
Questions fréquemment posées
- Markdown est-il le même partout ou existe-t-il des variations ?
- Il existe plusieurs 'saveurs' de Markdown. Le CommonMark est la spécification standardisée. Le GFM (GitHub Flavored Markdown) ajoute les tableaux, cases à cocher et le texte barré. MDX ajoute le support JSX pour les composants React. Notion a son propre sous-ensemble de Markdown. L'éditeur WikiPlus supporte CommonMark + GFM, ce qui couvre la majorité des plateformes courantes.
- Comment insérer des caractères spéciaux qui font partie de la syntaxe Markdown ?
- Pour afficher un caractère de syntaxe Markdown (comme *, # ou `) sans qu'il soit interprété, faites-le précéder d'un backslash (\). Exemples : \* pour un astérisque visible, \# pour un dièse visible, \`pour un backtick visible. Cette technique fonctionne pour tous les caractères de syntaxe Markdown.
- Peut-on inclure du HTML dans un fichier Markdown ?
- Oui. Le Markdown supporte le HTML inline : vous pouvez inclure des balises HTML directement dans votre texte Markdown. Les balises les plus utilisées sont div, span, br (retour à la ligne forcé), sup (exposant), sub (indice) et abbr (abréviation). L'éditeur WikiPlus rend le HTML inline dans la prévisualisation.