Syntaxe Markdown : aide-mémoire par usage

Markdown est du texte brut avec quelques marques simples. Cette page est un aide-mémoire. Trouve ce que tu veux faire, copie l’exemple et c’est parti.

Certaines marques fonctionnent partout. D’autres ne fonctionnent que dans certaines applications. Chaque section indique de quel type il s’agit :

  • Base : fait partie de CommonMark, la norme de référence. Fonctionne presque partout.
  • GFM : une extension de GitHub Flavored Markdown, qui complète CommonMark. La plupart des applications la prennent en charge.
  • Fonction GitHub : très répandue, mais dans aucune des deux spécifications. Vérifie ton application.

Titres (base)

Commence la ligne par une à six marques #, puis un espace. Plus il y a de marques #, plus le titre est petit.

# Title
## Section
### Subsection

L’espace compte. Sept marques # ne forment pas un titre.

Paragraphes et retours à la ligne (base)

Une ligne vide commence un nouveau paragraphe. Un simple retour à la ligne à l’intérieur d’un paragraphe ne coupe pas la ligne. Le texte continue.

Pour un retour à la ligne sans nouveau paragraphe, termine la ligne par deux espaces ou une barre oblique inverse :

First line\
Second line

Gras, italique et barré

*italic* or _italic_
**bold** or __bold__
***bold and italic***
~~strikethrough~~

L’italique et le gras font partie de la base. Le barré est GFM. Utilise les astérisques si la marque se trouve au milieu d’un mot, car _ ne fonctionne pas à l’intérieur d’un mot.

Listes

- Apples
- Bananas
  - Green ones
  - Yellow ones

1. Wake up
2. Make tea
3. Read

- [ ] Write the draft
- [x] Send the draft

Les puces peuvent commencer par -, + ou *. Les listes numérotées utilisent un nombre suivi de . ou ). Le premier nombre fixe le début de la liste.

Pour imbriquer une liste, décale la liste intérieure pour qu’elle s’aligne avec le texte de l’élément au-dessus. Pour - Bananas, cela fait deux espaces.

Les puces et les numéros font partie de la base. Les listes de tâches, avec les cases [ ] et [x], sont GFM.

Liens

[PilcrowMD](https://pilcrowmd.com "Optional title")
<https://pilcrowmd.com>
https://pilcrowmd.com

Le premier est un lien en ligne : le texte entre crochets, l’adresse entre parenthèses. Le deuxième est un lien automatique entre chevrons. Les deux font partie de la base.

Le troisième est une adresse brute, sans marque. CommonMark n’en fait pas un lien. GFM le fait, pour les adresses qui commencent par http://, https:// ou www..

Liens vers un titre

Pour aller à un titre du même fichier, faites un lien vers son ancre :

## My first section

[Go to the section](#my-first-section)

Le lien est un lien en ligne ordinaire. Sur GitHub, l’ancre est construite à partir du texte du titre : lettres en minuscules, espaces remplacées par des tirets, autre ponctuation supprimée. Un deuxième titre avec le même texte reçoit -1 en plus. D’autres applications peuvent construire les ancres de la même façon, mais c’est une règle de GitHub, alors teste.

Images

Comme un lien, avec un ! devant :

![A red apple on a table](apple.jpg)

Le texte entre crochets est la description (le texte alternatif). La syntaxe des images fait partie de la base.

Citations (base)

Commence chaque ligne par > :

> The best way to learn is to try.

Code

Pour un court morceau de code dans une phrase, utilise des accents graves simples :

Run `npm test` before you commit.

Pour montrer un accent grave dans le code, entoure le code de doubles accents graves.

Pour un bloc, utilise une clôture de trois accents graves. Écris le nom du langage après la clôture ouvrante :

```python
print("Hello")
```

Les clôtures peuvent aussi être faites avec trois tildes ~~~. Le nom du langage est facultatif. Les applications s’en servent pour colorer le code. Tout cela fait partie de la base.

Ligne horizontale (base)

Trois -, * ou _ ou plus, seuls sur une ligne :

---

Laisse une ligne vide au-dessus de ---. Juste sous une ligne de texte, cela transforme ce texte en titre.

Tableaux (GFM)

Un tableau demande une ligne d’en-tête, une ligne de tirets et des lignes de données :

| Fruit  | Price |
|--------|-------|
| Apple  | 1.20  |

Les tableaux ont d’autres règles, comme l’alignement et l’échappement de la barre verticale. Voir Tableaux Markdown : comment les écrire et les lire.

Échappement : afficher une marque comme du texte (base)

Place une barre oblique inverse avant une marque pour l’afficher comme du texte brut :

\*not italic\*

N’importe quel signe de ponctuation peut être échappé ainsi. Les barres obliques inverses ne fonctionnent pas à l’intérieur du code.

Notes de bas de page (fonction GitHub)

This claim needs a source.[^1]

[^1]: Here is the source.

Les notes de bas de page ne font partie ni de CommonMark ni de la spécification GFM. GitHub les prend en charge. Le texte de la note apparaît en bas de la page, où que tu l’écrives dans le fichier. GitHub ne prend pas en charge les notes de bas de page dans les wikis.

Encadrés (fonction GitHub)

Un encadré est une citation avec une étiquette sur la première ligne :

> [!NOTE]
> Useful information the reader should know.

Les types sont NOTE, TIP, IMPORTANT, WARNING et CAUTION. Ils ne font partie d’aucune des deux spécifications. Utilise-les avec parcimonie.

Lire du Markdown

Dans un éditeur de texte brut, toutes ces marques restent visibles. Un lecteur Markdown les transforme en une page propre.

PilcrowMD affiche les tableaux, les notes de bas de page, les encadrés de style GitHub et les liens qui mènent à un titre, sur Android et Mac. Sur Mac, il affiche aussi les listes de tâches.

Questions fréquentes

Quel Markdown dois-je apprendre en premier ? Les marques de base : titres, gras, italique, listes, liens, code et citations. Elles fonctionnent dans toutes les applications Markdown. Ajoute ensuite les tableaux et les listes de tâches, car la plupart des applications prennent en charge GFM.

Pourquoi mon Markdown s’affiche-t-il différemment dans une autre application ? Les applications suivent des règles différentes. CommonMark est la base, GFM la complète, et certaines fonctions, comme les notes de bas de page et les encadrés, ne figurent dans aucune des deux. Si une marque ne fonctionne pas, l’application ne la prend probablement pas en charge.

Dois-je mettre des espaces après # et - ? Oui. Écris # Title et - Item. Sans l’espace, la ligne reste du texte brut.

Aussi sur Mac : PilcrowMD pour Mac (bêta)