Aide-mémoire Markdown

2025-09-22 par Damien Mégy   markdown latex

Le Markdown est un langage de balisage léger qui permet d’écrire du texte lisible tout en le formatant facilement pour le web.
Il est très utilisé pour la documentation, les blogs, et s'intègre bien avec LaTeX. Il est surtout bien plus facile à utiliser que le HTML, même s'il n'entre pas en compétition avec lui. L'idée est surtout que les humains écrivent du Markdown, qui sera ensuite éventuellement transformé en HTML pour un affichage sur le web. Le fichier Markdown aura l'avantage d'être très lisible, simple à écrire et à modifier, et ne produira pas autant de bugs et d'erreurs que du HTML.

Les billets de ce blog sont écrits en Markdown, en particulier cette introduction au langage Markdown est elle-même un fichier Markdown!

Cette antisèche présente les principales fonctionnalités du Markdown moderne (version GitHub Flavored Markdown, ou GFM).

Même si certains passages de ce document mentionnent des fonctionnalités liées à HTML, il n'est pas nécessaire d'avoir ds connaissances en HTML pour apprendre Markdown ou pour lire ce document.

¶Qu'est-ce qu'un fichier Markdown ? Comment le créer ?

1. Un fichier Markdown est un simple fichier texte, mais se termine (par convention) par l'extension '.md' au lieu de '.txt'. Il est lisible sur toutes les plateformes, par une myriade de logiciels : Notepad et Notepad++ sous Windows, TextEdit sous MacOS, Vi, Vim, Neovim, Emacs, Nano etc sous Linux ou MacOS, Vscode, Sublime Text etc.

2. On crée un fichier Markdown comme on crée un fichier texte standard, c'est-à-dire :

• sous windows : "clic droit > nouveau fichier texte" puis on renomme le fichier en changeant l'extension .txt en .md (si Windows a le bon goût de ne pas masquer les extension...)
• sous macOS ou linux on peut ouvrir son éditeur de texte préféré, puis "Fichier > Nouveau fichier texte", ou bien créer le fichier en ligne de commande : touch monfichier.md, ou le créer et l'ouvrir à la volée avec son logiciel préféré : nano monfichier.md, vi monfichier.md etc.

¶Titres

Les titres sont créés avec des dièses # :

# Titre de niveau 1 ## Titre de niveau 2 ### Titre de niveau 3

¶Titre de niveau 1

¶Titre de niveau 2

¶Titre de niveau 3

¶Texte et emphase

Texte normal,
*italique*,
**gras**,
***gras et italique***
et ~~barré~~.

Remarquer qu'un seul saut de ligne n'a pas d'effet, il faut deux sauts de ligne (donc une ligne vide) pour changer de paragraphe.


(Insérer trois sauts de ligne ne rajoute pas plus d'espace.)

Texte normal, italique, gras, gras et italique et barré.

Remarquer qu'un seul saut de ligne n'a pas d'effet, il faut deux sauts de ligne (donc une ligne vide) pour changer de paragraphe.

(Insérer trois sauts de ligne ne rajoute pas plus d'espace.)

¶Caractères accentués et spéciaux

Un fichier Markdown est un fichier texte encodé en général au format unicode, il gère donc tous les caractères accentués que l'on peut imaginer, et on peut les entrer directement dans le corps du texte tels quels. (Et accentuez vos majuscules bon sang ! Étonnamment peu de gens le font. À croire qu'on est encore au XXe siècle avec des machines à écrire.)

Les Emojis sont aussi utilisables 🥳 et même, même, les tirets quadratins – même s'il vaut mieux maintenant les éviter pour éviter la suspicion de fraude/aide à l'IA ! De toute façon, il vaut mieux éviter, dans un fichier Markdown, d'utiliser des tirets non standard, car les tirets ont déjà un rôle spécial (pour les listes, voir plus bas).

¶Mise en forme en utilisant du HTML :

On peut mettre du HTML dans du Markdown. Moralement, c'est un peu de la triche et ça dénature le concept du Markdown mais ça peut être bien pratique.

En particulier on peut faire des choses comme :

- <mark>texte surligné</mark>
- <u>text souligné</u>
- Indices et exposants : H<sub>2</sub>O, x<sup>2</sup>. Ne pas utiliser ceci pour les mathématiques, voir plus bas la section sur $\LaTeX$.
- Texte centré: <div style="text-align:center">Mon texte centré</div>

• texte surligné
• text souligné
• Indices et exposants : H₂O, x². Ne pas utiliser ceci pour les mathématiques, voir plus bas la section sur $\LaTeX$.
• Texte centré:
  Mon texte centré

Ne pas abuser du HTML, ça diminue la lisibilité, Markdown a été inventé pour une bonne raison ! Par exemple, ne pas utiliser <i>ceci</i> pour mettre du texte en italique. Utiliser _ceci_, comme expliqué plus haut. Si l'on veut produire le résultat le même résultat que H<sub>2</sub>O ou x<sup>2</sup> sans utiliser LaTeX ni HTML, on peut simplement écrire les caractères unicode : H₂O et x².

¶Liens et e-mails

[Lien vers le site Animathor](https://www.animathor.fr).
Version rapide : <https://www.animathor.fr>.
Lien vers email (ouvre le client mail) : <lolno@gmail.com>

Lien vers le site Animathor. Version rapide : https://www.animathor.fr. Lien vers email (ouvre le client mail) : lolno@gmail.com

¶Images

Markdown permet d'insérer des images. L'image du début de la page peut être insérée avec le code suivant, qui fournit un texte de remplacement en cas de problème de chargement de l'image, ainsi qu'une légende qui s'affiche lors du survol avec la souris :

![Texte de remplacement](https://i.kym-cdn.com/entries/icons/original/000/012/886/wntgd.jpg "Texte affiché au survol de l'image")

(Ou simplement la version courte ![](https://i.kym-cdn.com/entries/icons/original/000/012/886/wntgd.jpg))

L'image ne doit pas forcément être en ligne, elle peut être stockée localement. On peut aussi mettre plusieurs images sur la même ligne, comme ci-dessous (captures d'écran d'animathor.fr).

![Page d'accueil](../assets/screenshot-home.png)
 
![Écran de jeu](../assets/screenshot-play.png)
 
![Réglages de difficulté](../assets/screenshot-settings.png)

Noter l'utilisation de   qui produit un espace insécable («nonbreaking space») entre les images. (Oui je sais qu'il faudrait dire une espace insécable.)

¶Listes

¶Liste non ordonnée

- Élément
  - Sous-élément
- Élément suivant

• Élément
  • Sous-élément
• Élément suivant

¶Liste ordonnée

1. Premier
2. Deuxième
3. Troisième

1. Premier
2. Deuxième
3. Troisième

¶Listes de tâches (GFM)

- [x] Fait
- [ ] À faire
- [ ] En cours

• Fait
• À faire
• En cours

¶Citations

> Ceci est une **citation**.
>
> Elle peut contenir *plusieurs paragraphes*.

Ceci est une citation.

Elle peut contenir plusieurs paragraphes.

Les citations peuvent être imbriquées, comme ceci:

> Citation 1
>> Citation 2

Citation 1

Citation 2

¶Code

Bloc de code :

```python
def fibonacci(n: int) -> int:
  if n == 0:
    return 0
  if n == 1:
    return 1
  return fibonacci(n-1) + fibonacci(n-2)

fibonacci(50) # Partez prendre un café, prenez un extincteur en revenant au cas où
```

Le code précédent produit le bloc de code suivant :

def fibonacci(n: int) -> int:
  if n == 0:
    return 0
  if n == 1:
    return 1
  return fibonacci(n-1) + fibonacci(n-2)

fibonacci(50) # Partez prendre un café, prenez un extincteur en revenant au cas où

Parfois, on ne veut pas avoir un bloc de code complet, mais on veut pouvoir insérer des petits bouts de code au milieu d'un paragraphe de texte. On faire y parvenir grâce aux balises de code "en ligne" :

En langage C, on peut écrire `int a=0;`. En javascript, on écrit `let a=0;`.

En langage C, on peut écrire int a=0;. En javascript, on écrit let a=0;.

¶Tableaux

| Nom | Rôle | Centré | Aligné à droite |
|:----|:-----|:------:|----------------:|
| Alice | Admin | ✅ | 8890 |
| Bob | Auteur | ❌ | 7 |
| Charles | Parasite | ⚠️ | 23|

¶Séparateurs et retours à la ligne

Trois tirets, étoiles ou underscores :

---
***
___

Saut de ligne manuel : deux espaces à la fin d’une ligne.

¶Détails / résumé (contenu caché)

<details>
  <summary>Cliquer pour afficher</summary>

  Contenu caché **rédigé en Markdown**.

</details>

¶Notes de bas de page

Une phrase avec une note[^1].
(Cliquer pour lire la note tout en bas de la page. À tout de suite.)

[^1]: Ceci est la note de bas de page. (On **doit** laisser une ligne vide avant.)
On peut aller à la ligne dans la note de bas de page mais le saut de ligne sera ignoré comme d'habitude.
On peut cliquer pour remonter mais c'est quand même un peu pénible.

On ne peut pas changer de paragraphe dans la note de base de page.

Une phrase avec une note¹. (Cliquer pour lire la note tout en bas de la page. À tout de suite.)

On ne peut pas changer de paragraphe dans la note de base de page.

Remarque

Sur le web, il vaut mieux éviter les notes de bas de page. Remplacer par :

• une remarque ou une note dans un bloc comme celui-ci,
• un élément html details comme présenté au point précédent,
• une incise avec un tiret long – ChatGPT serait fier,
• ... ou simplement une phrase entre parenthèses. C'est très bien les parenthèses.

À ce sujet, lire l'article Give footnotes the boot de Jake Archibald.

¶Mathématiques (LaTeX)

Formule en ligne : $E = mc^2$

Bloc de formule :

\[
\sum_{n=1}^{+\infty} \frac{1}{n^2} = \frac{\pi^2}{6}
\qquad\text{et}\qquad
\int_0^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
\]

Formule en ligne : $E = mc^2$

Bloc de formule :

\[ \sum_{n=1}^{+\infty} \frac{1}{n^2} = \frac{\pi^2}{6} \qquad\text{et}\qquad \int_0^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2} \]

¶Diagrammes Mermaid (GFM)

Des extensions permettent d'étendre les fonctionnalités de base de Markdown. On peut notamment tracer assez facilement des graphes ou des schémas avec l'extension Mermaid :

```mermaid
flowchart TD
  A[Début] --> B{Ça bouge ?}
  B -- Oui --> C{Ça devrait ?}
  B -- Non --> D{Ça devrait ?}
  C -- Oui --> I[✅]
  C -- Non --> F[Mettre du scotch]
  D -- Non --> I
  D -- Oui --> H[Mettre du WD40]
  F --> I
  H --> I
```

¶Insertion de HTML brut

Comme on l'a vu plu shaut, on peut insérer du HTML brut dans du Markdown. Cela peut parfois avoir un interêt pour agir sur la mise en page avec des feuilles de styles spéciales.

<div style="border:2px dashed red; padding:1em;">
  **Attention** : Le *Markdown* ne marche plus à l'intérieur du bloc HTML. Il
  faut donc utiliser des balises HTML pour l'<strong>accent</strong> et
  l'<em>emphase</em>. (Éviter les vieilles balises <b>gras</b> et
  <i>italique</i>.)
</div>

¶Échappement de caractères

\*Ce texte n’est pas en italique\*
\# Ce n’est pas un titre

*Ce texte n’est pas en italique*
# Ce n’est pas un titre

¶Ressources

• Spécification GFM officielle (GitHub)
• Cheatsheet Markdown originale
• Convertisseur en ligne Markdown → HTML