La plupart des documents commencent comme un simple fichier texte avec quelques astérisques et dièses. Ce fichier est généralement en Markdown. Ce n'est pas la seule façon d'écrire pour le web, mais c'est le format par défaut des README, outils de suivi de tickets, chatbots et sites statiques, car la source reste lisible avant d'être rendue.
Cet article est un tutoriel rapide et pratique. Il suppose que vous avez dix minutes et un éditeur de texte. Aucune installation requise.
Qu'est-ce que Markdown
Markdown est une syntaxe de balisage légère. John Gruber a publié la spécification originale en 2004 avec un objectif : un format lisible en texte brut et qui se convertit proprement en HTML. Depuis, il est devenu le format d'entrée de GitHub, Obsidian, Notion, de nombreux générateurs de sites statiques et de la plupart des sorties des grands modèles de langage.
L'idée de base est simple. On marque la structure avec de la ponctuation plutôt qu'avec des balises :
# Ceci est un titre
Ceci est un paragraphe.
- Ceci est un élément de liste
- Ceci est un autre élément
Un analyseur transforme cela en HTML. Différents analyseurs prennent en charge différentes extensions, c'est là que les standards entrent en jeu.
Les standards Markdown comptent
Markdown n'a pas de standard officiel unique. La spécification originale de Gruber laisse des lacunes, que différents outils ont comblées de manière incompatible. Si vous écrivez un tableau dans une application et le collez dans une autre, il peut être cassé. Il faut savoir quel dialecte vous ciblez.
- CommonMark. Une spécification stricte et bien testée, lancée en 2014. Elle définit précisément la syntaxe de base. Si vous voulez de la portabilité, écrivez en CommonMark.
- GitHub Flavored Markdown (GFM). Ajoute les tableaux, listes de tâches, barrés, blocs de code délimités et liens automatiques. C'est ce que vous voyez dans les README et commentaires GitHub.
- Pandoc Markdown. Ajoute les citations, notes de bas de page, listes de définitions, indices, exposants et mathématiques. Courant dans l'écriture académique.
- Obsidian / Quarto / MDX. Ajoutent les liens wiki, encarts, cellules de code exécutables ou composants embarqués. Puissants mais peu portables.
Pour le travail quotidien, GFM est la cible la plus sûre. Pour des documents longs qui peuvent circuler entre outils, CommonMark plus un ensemble d'extensions documenté est préférable.
Bases de Markdown
Titres
Utilisez un à six dièses. Un seul donne le plus grand titre.
# Titre 1
## Titre 2
### Titre 3
Paragraphes et sauts de ligne
Séparez les paragraphes par une ligne vide. Terminez une ligne par deux espaces ou une barre oblique inverse pour forcer un saut de ligne.
Ceci est le premier paragraphe.
Ceci est le second.
Emphase
_italique_ ou _italique_
**gras** ou **gras**
**_gras et italique_**
~~barré~~ (GFM uniquement)
Listes
Les listes non ordonnées utilisent -, * ou + :
- Élément un
- Élément deux
- Élément imbriqué
Les listes ordonnées utilisent des nombres :
1. Étape une
2. Étape deux
3. Étape trois
Les nombres n'ont pas besoin d'être corrects. Markdown les renumérote au rendu. Utilisez tout de même des nombres séquentiels pour que la source reste lisible.
Liens et images
[Texte du lien](https://example.com)
[Lien avec titre](https://example.com "Titre")
Pour les liens internes, utilisez des chemins relatifs :
[Convertir Markdown en PDF](/tools/markdown-to-pdf)
Code
Le code en ligne utilise des backticks simples : `console.log("hi")`.
Les blocs de code utilisent trois backticks :
```python
def hello():
return "hello"
```
Ajoutez un identifiant de langue après les backticks ouvrants pour que la coloration syntaxique fonctionne.
## Astuces courantes et exemples
### Citations
```markdown
> Ceci est une citation.
> Elle peut s'étendre sur plusieurs lignes.
Vous pouvez les imbriquer :
> Citation externe
>
> > Citation imbriquée
Lignes horizontales
---
Utilisez trois tirets, astérisques ou underscores seuls sur une ligne.
Listes de tâches
GFM prend en charge les cases à cocher :
- [x] Rédiger le brouillon
- [ ] Vérifier les tableaux
- [ ] Publier l'article
Elles s'affichent comme des cases désactivées en HTML. Ne les utilisez pas comme substitut à de vrais champs de formulaire.
Échappement de caractères
Préfixez les caractères Markdown d'une barre oblique inverse pour les afficher littéralement :
\*pas en italique\*
\# pas un titre
Astuces avancées et exemples
Tableaux
Les tableaux sont une extension GFM, pas une partie de la spécification Markdown originale.
| Fonction | CommonMark | GFM |
| ---------------- | ---------- | --- |
| Tableaux | Non | Oui |
| Listes de tâches | Non | Oui |
L'alignement est optionnel :
| Gauche | Centre | Droite |
| :----- | :----: | -----: |
| A | B | C |
Gardez les tableaux simples. Les tableaux imbriqués, les fusions de lignes et de colonnes ne sont pas standard et échouent souvent.
Notes de bas de page
Pandoc et certains analyseurs GFM prennent en charge les notes de bas de page :
Voici une affirmation.[^1]
[^1]: Ceci est le texte de la note de bas de page.
Si vous avez besoin de notes de bas de page dans un PDF rendu, utilisez un convertisseur prenant en charge la syntaxe Pandoc ou insérez-les manuellement.
Mathématiques
Pandoc et de nombreux éditeurs modernes prennent en charge les mathématiques LaTeX :
Mathématiques en ligne : $E = mc^2$
Mathématiques en bloc :
$$
\int_a^b f(x) \, dx = F(b) - F(a)
$$
Le rendu mathématique dépend de l'analyseur et du format de sortie. HTML nécessite généralement MathJax ou KaTeX. Les convertisseurs PDF nécessitent souvent un backend LaTeX.
Listes de définitions
Une autre extension Pandoc :
Terme
: Définition du terme.
Autre terme
: Une autre définition.
HTML dans Markdown
Quand Markdown ne suffit pas, vous pouvez utiliser HTML directement :
<p style="color: red;">Ce texte est rouge.</p>
Cela fonctionne pour la mise en page, les vidéos embarquées ou les attributs non supportés par Markdown. Cela réduit la portabilité, donc utilisez-le avec parcimonie.
Quand convertir Markdown
Markdown est excellent pour écrire et le contrôle de version. Il est mauvais pour les documents finaux qui doivent avoir exactement le même aspect partout. C'est pourquoi les convertisseurs existent.
Si vous avez un brouillon Markdown à transformer en PDF partageable, utilisez le convertisseur Markdown vers PDF. Il fonctionne dans le navigateur, votre fichier ne quitte donc pas votre machine.
Si vous partez d'un PDF et voulez du Markdown éditable, utilisez le convertisseur PDF vers Markdown. Il extrait les titres, listes et paragraphes sans rien télécharger sur un serveur.
Antisèche Markdown
| Élément | Syntaxe | Rendu |
|---|---|---|
| Titre 1 | # H1 | H1 |
| Titre 2 | ## H2 | H2 |
| Titre 3 | ### H3 | H3 |
| Gras | **bold** | bold |
| Italique | *italic* | italic |
| Barré | ~~text~~ | |
| Code en ligne | `code` | code |
| Lien | [text](url) | text |
| Image |  | image |
| Citation | > quote | citation |
| Liste non ordonnée | - item | élément de liste |
| Liste ordonnée | 1. item | élément de liste |
| Ligne horizontale | --- | ligne horizontale |
| Bloc de code | ```lang | bloc avec coloration syntaxique |
| Liste de tâches | - [ ] task | case à cocher |
| Tableau | | a | b | | tableau |
Imprimez ce tableau, collez-le sur votre écran, et vous n'aurez plus besoin de chercher la syntaxe Markdown.
Notes finales
Markdown récompense la retenue. Utilisez la syntaxe de base pour 90% de ce que vous écrivez. Ne recourez aux tableaux, notes de bas de page et HTML que lorsque le document en a réellement besoin. Si vous vous en tenez à CommonMark ou GFM, vos fichiers circuleront entre éditeurs, plateformes et convertisseurs sans mauvaise surprise.
