Listes Markdown : puces, numérotation, imbrication et cases à cocher

Une liste Markdown commence souvent par un simple tiret. Puis on ajoute un sous-élément, une case à cocher, un second paragraphe ou un bloc de code, et ce qui semblait évident dépend soudain de quelques espaces invisibles.

La syntaxe de base pour écrire des listes et cases à cocher en markdown est simple :

- Un élément à puce
- Un autre élément

1. Première étape
2. Deuxième étape

- [ ] Tâche à faire
- [x] Tâche terminée

Dans ce guide, je vais partir de ces trois formes, puis expliquer la numérotation automatique, les listes imbriquées, le contenu sur plusieurs lignes, les cases à cocher et les différences entre GitHub, Obsidian et Fude.

Si les fichiers .md sont encore nouveaux pour vous, commencez par lire mon article Fichier Markdown (.md) : qu'est-ce que c'est et comment l'ouvrir ?.

1. Choisir le bon type de liste Markdown

Markdown propose trois familles de listes :

Objectif	Syntaxe	À utiliser quand
Liste à puces	- Élément	L'ordre n'a pas d'importance
Liste numérotée	1. Étape	L'ordre ou la progression compte
Liste de tâches	- [ ] Tâche	Chaque élément possède un état à faire ou terminé

Voici le même contenu exprimé de trois façons :

# Informations sans ordre particulier
- Documentation
- Tests
- Publication

# Étapes à suivre dans l'ordre
1. Écrire la documentation
2. Lancer les tests
3. Publier la version

# Travail à suivre
- [x] Écrire la documentation
- [ ] Lancer les tests
- [ ] Publier la version

Rendu :

Informations sans ordre particulier

• Documentation
• Tests
• Publication

Étapes à suivre dans l'ordre

1. Écrire la documentation
2. Lancer les tests
3. Publier la version

Travail à suivre

• Écrire la documentation
• Lancer les tests
• Publier la version

Le choix ne doit pas être seulement visuel. Une liste numérotée indique au lecteur qu'il existe une séquence. Une case à cocher transforme un élément descriptif en tâche. Si ces informations ne sont pas utiles, une liste à puces reste plus simple.

2. Créer une liste à puces

Pour créer une liste non ordonnée, placez un tiret suivi d'un espace devant chaque élément :

- Pommes
- Poires
- Abricots

Rendu :

• Pommes
• Poires
• Abricots

L'espace après le tiret est indispensable :

- Élément valide
-Élément invalide

La seconde ligne reste généralement du texte brut, car -Élément ne contient aucun espace entre le marqueur et le contenu.

Tiret, astérisque ou signe plus ?

La syntaxe Markdown accepte trois marqueurs pour les listes à puces :

- Avec un tiret
* Avec un astérisque
+ Avec un signe plus

Rendu :

• Avec un tiret
• Avec un astérisque
• Avec un signe plus

Les trois produisent une puce. Je recommande malgré tout le tiret - : il est facile à lire dans la source et évite la confusion avec l'astérisque utilisé pour le gras et l'italique.

Gardez également le même marqueur dans une liste. Changer de caractère peut créer deux listes distinctes selon le moteur :

- Premier groupe
- Même groupe

* Nouveau groupe potentiel
* Même nouveau groupe

Une ligne vide rend ici la séparation volontaire. Sans elle, le résultat peut sembler identique à l'écran alors que la structure HTML contient plusieurs listes.

Ajouter une phrase avant la liste

Je laisse une ligne vide avant et après une liste :

Le document contient trois sections :

- introduction ;
- analyse ;
- conclusion.

La section suivante détaille l'analyse.

Les lecteurs Markdown savent souvent reconnaître une liste sans cette ligne vide. L'ajouter rend cependant la source plus claire et évite les différences avec des moteurs plus anciens ou plus stricts.

3. Créer une liste numérotée

Une liste ordonnée utilise un nombre, un point et un espace :

1. Installer l'application
2. Ajouter un projet
3. Ouvrir un fichier Markdown

Rendu :

1. Installer l'application
2. Ajouter un projet
3. Ouvrir un fichier Markdown

Le numéro fait partie du marqueur. 1.Installation ne fonctionne pas correctement, car il manque l'espace après le point.

Certains lecteurs Markdown acceptent aussi une parenthèse fermante :

1) Première étape
2) Deuxième étape

Cette forme est valide dans les moteurs compatibles, mais 1. reste la syntaxe la plus familière et la plus portable. C'est celle que j'utilise dans les guides du blog.

Faut-il écrire tous les vrais numéros ?

Le moteur Markdown détermine le numéro de départ à partir du premier élément, puis calcule la suite. Ces deux sources peuvent donc produire 1, 2, 3 dans le rendu :

1. Préparer
2. Vérifier
3. Publier

1. Préparer
1. Vérifier
1. Publier

Rendu dans les deux cas :

1. Préparer
2. Vérifier
3. Publier

Répéter 1. possède un avantage : vous pouvez déplacer ou insérer une étape sans renuméroter toutes les lignes suivantes.

Je préfère néanmoins écrire les vrais numéros dans un document destiné à être lu aussi sous forme de texte brut. Le rendu reste correct dans les deux cas, mais 1., 2., 3. est plus compréhensible lorsque le fichier apparaît dans un terminal, un diff Git ou un éditeur sans aperçu.

Commencer à un autre numéro

Pour reprendre une procédure à l'étape 4, commencez la nouvelle liste par 4. :

4. Redémarrer l'application
5. Vérifier le résultat
6. Archiver le journal

Dans la plupart des lecteurs Markdown, le premier marqueur fixe le numéro de départ. Les nombres suivants ne contrôlent pas nécessairement chaque numéro affiché : le lecteur poursuit généralement la séquence lui-même.

Cette nuance explique un résultat parfois surprenant :

4. Redémarrer l'application
9. Vérifier le résultat
2. Archiver le journal

Le rendu peut afficher 4, 5, 6. Pour éviter de tromper la personne qui relit la source, gardez une numérotation cohérente même lorsque le parseur sait la corriger.

Éviter une liste numérotée accidentelle

Une phrase qui commence par une année suivie d'un point peut être interprétée comme une liste :

1986. Une année importante pour le projet.

Échappez le point avec une barre oblique inversée si vous voulez conserver une phrase normale :

1986\. Une année importante pour le projet.

Rendu : 1986. Une année importante pour le projet.

4. Créer une liste imbriquée

Une liste imbriquée place une liste à l'intérieur d'un élément parent. Indentez les sous-éléments avec quatre espaces :

- Documentation
    - Guide d'installation
    - Guide de contribution
- Application
    - Lecteur
    - Bibliothèque de projets

Rendu :

• Documentation
  • Guide d'installation
  • Guide de contribution
• Application
  • Lecteur
  • Bibliothèque de projets

Quatre espaces constituent une règle simple et portable. Certains moteurs acceptent deux ou trois espaces dans des cas simples, mais le résultat devient plus fragile lorsque les marqueurs sont plus longs ou que l'élément contient plusieurs blocs.

La règle précise consiste à aligner le contenu imbriqué avec le début du texte de l'élément parent. Comparez :

1. Premier élément
   - Sous-élément

100. Centième élément
     - Sous-élément

Le marqueur 100. occupe plus de place que 1.. Son sous-élément a donc besoin d'une indentation supplémentaire pour rester attaché au bon parent.

Ajouter plusieurs niveaux

Vous pouvez répéter l'indentation :

- Projet
    - Application
        - Interface
        - Stockage
    - Site web
        - Blog
        - Documentation

Rendu :

• Projet
  • Application
    • Interface
    • Stockage
  • Site web
    • Blog
    • Documentation

Techniquement, les listes peuvent contenir de nombreux niveaux. En pratique, trois niveaux suffisent presque toujours. Au-delà, la structure devient difficile à parcourir sur un petit écran et pénible à maintenir dans la source.

Si vous avez besoin de cinq ou six niveaux, des titres et sous-titres décrivent probablement mieux la hiérarchie.

5. Mélanger les puces et les numéros

Une liste numérotée peut contenir des puces :

1. Préparer le document
    - vérifier le titre ;
    - ajouter une description ;
    - relire les liens.
2. Vérifier le rendu
    - ouvrir le fichier ;
    - contrôler les images ;
    - tester les exemples.
3. Publier

Rendu :

1. Préparer le document
   • vérifier le titre ;
   • ajouter une description ;
   • relire les liens.
2. Vérifier le rendu
   • ouvrir le fichier ;
   • contrôler les images ;
   • tester les exemples.
3. Publier

L'inverse fonctionne aussi :

- Version Mac
    1. Télécharger l'application
    2. Déplacer Fude dans Applications
- Version Windows
    1. Télécharger l'installateur
    2. Suivre les étapes affichées

Rendu :

• Version Mac
  1. Télécharger l'application
  2. Déplacer Fude dans Applications
• Version Windows
  1. Télécharger l'installateur
  2. Suivre les étapes affichées

Le type de chaque niveau doit exprimer son rôle. Les puces regroupent des options ou des détails ; les numéros décrivent une séquence à suivre.

6. Ajouter des cases à cocher en Markdown

Une liste de tâches, souvent appelée checklist Markdown, est une liste dont chaque élément commence par une paire de crochets. Le tiret reste le marqueur le plus courant :

- [ ] Préparer le brouillon
- [x] Vérifier les exemples
- [ ] Publier l'article

Rendu :

• Préparer le brouillon
• Vérifier les exemples
• Publier l'article

Un espace entre les crochets représente une tâche ouverte. Un x, en minuscule ou en majuscule, représente une tâche terminée :

- [ ] À faire
- [x] Terminé
- [X] Également terminé

Les espaces comptent. Cette forme est correcte :

- [ ] Tâche ouverte

Ces formes ne le sont pas :

- [] Crochets sans espace intérieur
- [ ]Tâche sans espace après les crochets
[ ] Élément sans marqueur de liste

Les cases à cocher ne faisaient pas partie de la syntaxe Markdown d'origine. Elles ont été popularisées par GitHub et sont aujourd'hui comprises par GitHub, Obsidian, Fude et de nombreux outils modernes.

Cette extension autorise aussi les cases dans une liste numérotée :

1. [x] Préparer le brouillon
2. [ ] Relire les exemples
3. [ ] Publier l'article

Rendu :

1. Préparer le brouillon
2. Relire les exemples
3. Publier l'article

Cette forme est valide, mais elle cumule deux informations : l'ordre des étapes et leur état. Utilisez-la pour une procédure à accomplir dans l'ordre. Pour une simple liste de choses à faire, les tirets sont plus naturels.

Imbriquer des tâches

Les listes de tâches suivent les mêmes règles d'indentation que les autres listes :

- [ ] Publier la nouvelle version
    - [x] Écrire les notes de version
    - [ ] Générer les fichiers d'installation
    - [ ] Envoyer l'annonce
- [ ] Préparer la version suivante

Rendu :

• Publier la nouvelle version
  • Écrire les notes de version
  • Générer les fichiers d'installation
  • Envoyer l'annonce
• Préparer la version suivante

Cocher tous les sous-éléments ne coche pas automatiquement le parent dans le format Markdown lui-même. Une application peut ajouter ce comportement, mais le fichier ne contient que les états [ ] et [x] que vous avez écrits.

Une case affichée n'est pas toujours interactive

Le rendu d'une case et sa modification sont deux sujets différents.

Un lecteur statique peut afficher une case cochée ou vide sans autoriser le clic. Un éditeur peut modifier directement la source lorsque vous cliquez. Sur GitHub, le comportement dépend aussi du contexte : les listes de tâches dans les issues et les pull requests disposent de fonctions de suivi que ne possède pas un simple fichier affiché ailleurs.

Pour garder un document portable, considérez toujours le texte comme la source de vérité : remplacez [ ] par [x] pour terminer une tâche, et faites l'inverse pour la rouvrir.

Peut-on mettre une case à cocher dans un tableau ?

Une case à cocher Markdown doit appartenir à un élément de liste. Placée seule dans une cellule de tableau, la séquence [ ] ne devient donc généralement pas une tâche :

| Tâche | État |
| --- | --- |
| Relire l'article | [ ] |
| Vérifier les liens | [x] |

Rendu dans la plupart des lecteurs Markdown :

Tâche	État
Relire l'article	[ ]
Vérifier les liens	[x]

Certains outils ajoutent leur propre interprétation, mais le résultat n'est pas portable. Pour une indication purement visuelle, vous pouvez utiliser les caractères ☐ et ☑. Ils restent du texte, ne sont pas interactifs et ne représentent pas un état de tâche Markdown.

Si vous avez besoin de vraies tâches, gardez une liste à cocher. Si vous devez comparer plusieurs propriétés par ligne, utilisez un tableau et choisissez un libellé comme « À faire » ou « Terminé ». Le guide sur les tableaux Markdown détaille leur syntaxe et leurs limites.

7. Mettre en forme le contenu d'une liste

Un élément de liste peut contenir la plupart des syntaxes en ligne :

- **Important** : sauvegarder le fichier
- *Facultatif* : changer le thème
- ~~Abandonné~~ : exporter en XML
- Consulter le [guide des liens](/fr/blog/comment-creer-liens-markdown/)

Rendu :

• Important : sauvegarder le fichier
• Facultatif : changer le thème
• Abandonné : exporter en XML
• Consulter le guide des liens

Le guide sur le gras, l'italique, le barré et le soulignement détaille les différences de compatibilité entre ces styles.

Ajouter plusieurs paragraphes dans un élément

Laissez une ligne vide, puis indentez le paragraphe suivant pour le garder dans le même élément :

1. Sauvegarder la base de données.

    Cette copie permet de revenir en arrière si la migration échoue.

2. Lancer la migration.

    Conservez le journal jusqu'à la validation complète.

Rendu :

1. Sauvegarder la base de données.

   Cette copie permet de revenir en arrière si la migration échoue.

2. Lancer la migration.

   Conservez le journal jusqu'à la validation complète.

Sans indentation, le second paragraphe peut sortir de la liste et couper la numérotation.

Ajouter une citation

Indentez également le marqueur > :

- Relire la règle avant de continuer.

    > Une sauvegarde non testée n'est pas encore une sauvegarde fiable.

- Vérifier la copie.

Rendu :

• Relire la règle avant de continuer.

  Une sauvegarde non testée n'est pas encore une sauvegarde fiable.

• Vérifier la copie.

Ajouter un bloc de code

Le bloc clôturé par trois backticks doit rester attaché à l'élément :

1. Exécuter la commande :

    ```bash
    pnpm test
    ```

2. Corriger les erreurs éventuelles.

Rendu :

1. Exécuter la commande :

   pnpm test

2. Corriger les erreurs éventuelles.

Les blocs clôturés sont généralement plus lisibles que les blocs créés uniquement avec des espaces, surtout à l'intérieur d'une liste déjà imbriquée.

Ajouter une image

Une image peut devenir le contenu d'un élément :

- Aperçu clair

    ![Interface en thème clair](./images/theme-clair.png)

- Aperçu sombre

    ![Interface en thème sombre](./images/theme-sombre.png)

Les chemins, le texte alternatif et les différences entre fichiers locaux et images web sont expliqués dans le guide Comment ajouter des images en Markdown.

8. Comprendre les listes compactes et aérées

Ces deux listes ne possèdent pas exactement la même structure :

- Premier élément
- Deuxième élément
- Troisième élément

- Premier élément

- Deuxième élément

- Troisième élément

Rendu compact :

• Premier élément
• Deuxième élément
• Troisième élément

Rendu aéré :

• Premier élément

• Deuxième élément

• Troisième élément

La première est une liste compacte, parfois appelée tight list. La seconde est une liste aérée, ou loose list. Dans cette dernière, chaque élément contient généralement un vrai paragraphe, ce qui ajoute de l'espace vertical selon la feuille de style du lecteur.

J'utilise les listes compactes pour des éléments courts. Je réserve les listes aérées aux éléments composés de plusieurs phrases ou de plusieurs blocs.

Ajouter des lignes vides au hasard pour « réparer » un rendu produit souvent l'effet inverse. Décidez si la liste doit être compacte ou aérée, puis appliquez la même structure à tous ses éléments.

9. Comparer GitHub, Obsidian et Fude

Les listes à puces, les listes numérotées et leur imbrication font partie du socle pris en charge par les trois outils. Les différences concernent surtout l'édition et les cases à cocher.

Sur GitHub

GitHub utilise sa propre variante de Markdown. Elle prend en charge :

• les listes à puces et numérotées ;
• les sous-listes à plusieurs niveaux ;
• les listes de tâches avec [ ] et [x] ;
• la mise en forme, les liens et les références à des issues dans les éléments.

Dans les zones d'édition GitHub, Tab et Maj + Tab permettent d'indenter ou de désindenter les lignes sélectionnées. Les listes de tâches placées dans les issues et les pull requests peuvent aussi participer au suivi du travail.

GitHub recommande d'aligner visuellement le marqueur d'une sous-liste avec le début du texte de l'élément parent. Cette méthode devient particulièrement utile lorsque la liste ordonnée commence par 100. au lieu de 1..

Dans Obsidian

Obsidian affiche les listes et permet de cocher les tâches depuis ses modes d'édition. Le clic modifie alors le fichier Markdown local en remplaçant l'état de la case.

Des thèmes et des extensions peuvent ajouter d'autres symboles ou états de tâches. Ces conventions restent propres à l'environnement Obsidian. Si le fichier doit être lu ailleurs, conservez [ ] et [x] pour les états essentiels.

Dans Fude

Fude prend en charge la variante de Markdown utilisée par GitHub, notamment ses listes de tâches. Les puces, les numéros, l'imbrication, le gras, les liens et les cases sont donc affichés dans le lecteur.

Fude reste un lecteur : impossible de cocher une case dans le rendu de votre fichier. L'état visible vient de [ ] ou [x] dans la source, que vous pouvez modifier avec votre éditeur ou avec un agent IA.

Quand une liste de tâches devient trop longue pour être parcourue verticalement, Fude peut aussi transformer un bloc dédié en tableau Kanban. Le guide Créer un tableau Kanban en Markdown avec Fude et les agents IA explique cette syntaxe propre au lecteur.

Vous pouvez coller tous les exemples de cet article dans le lecteur Markdown gratuit de Fude.md pour vérifier immédiatement leur rendu.

10. Résoudre les problèmes courants

« Mes tirets restent visibles comme du texte »

Vérifiez l'espace après le marqueur :

- correct
-incorrect

Assurez-vous aussi que vous regardez le rendu du document. Un éditeur en mode source affiche naturellement les tirets. Un lecteur les transforme en puces.

« Ma sous-liste reste au même niveau »

L'indentation est insuffisante ou incohérente. Utilisez quatre espaces et évitez de mélanger tabulations et espaces :

- Parent
    - Enfant

Activez l'affichage des caractères invisibles dans votre éditeur si deux lignes qui paraissent alignées ne se comportent pas de la même façon.

« Ma numérotation recommence à 1 »

Un paragraphe, un bloc de code ou une ligne mal indentée a probablement coupé la liste en deux. Vérifiez que le contenu intermédiaire appartient bien à l'élément précédent et qu'il est indenté.

Une séparation volontaire peut commencer à un autre numéro :

4. Reprendre à la quatrième étape

« Mes cases à cocher ne s'affichent pas »

Vérifiez les trois emplacements où un espace est nécessaire :

- [ ] Tâche

Il faut un espace après le tiret, un espace à l'intérieur des crochets pour une tâche ouverte, puis un espace après ].

Si la syntaxe est correcte mais que les crochets restent visibles, le lecteur ne prend probablement pas en charge les listes de tâches.

« Je peux voir la case, mais pas cliquer dessus »

Le lecteur affiche l'état sans proposer d'édition. Modifiez [ ] en [x] dans la source, ou ouvrez le fichier dans un éditeur qui sait répercuter le clic dans le Markdown.

« Trois astérisques créent une ligne horizontale »

Trois astérisques séparés peuvent être interprétés comme une ligne horizontale :

* * *

Pour créer trois éléments, placez chaque marqueur sur sa propre ligne avec son contenu :

* Premier élément
* Deuxième élément
* Troisième élément

Le guide Comment ajouter une ligne horizontale en Markdown détaille cette ambiguïté et les autres syntaxes possibles.

« Mon contenu sort de la liste »

Les paragraphes, citations, images et blocs de code qui appartiennent à un élément doivent rester indentés. Une ligne vide seule ne suffit pas à exprimer cette relation.

Quand le doute persiste, simplifiez temporairement l'élément : gardez seulement sa première ligne, vérifiez le rendu, puis réintroduisez les blocs un par un avec la même indentation.

11. Le mémo à copier

# Liste à puces
- Premier élément
- Deuxième élément
- Troisième élément

# Liste numérotée
1. Première étape
2. Deuxième étape
3. Troisième étape

# Numérotation automatique
1. Première étape
1. Deuxième étape
1. Troisième étape

# Liste imbriquée
- Parent
    - Enfant
        - Petit-enfant

# Puces dans une procédure
1. Préparer
    - sauvegarder les données
    - fermer l'application
2. Exécuter
3. Vérifier

# Cases à cocher — prises en charge par GitHub et de nombreux lecteurs
- [ ] Tâche ouverte
- [x] Tâche terminée

# Tâches imbriquées
- [ ] Publier
    - [x] Écrire
    - [ ] Relire
    - [ ] Mettre en ligne

# Plusieurs paragraphes dans un élément
1. Première étape.

    Explication toujours attachée à la première étape.

2. Deuxième étape.

# Bloc de code dans un élément
1. Lancer les tests :

    ```bash
    pnpm test
    ```

2. Vérifier le résultat.

# Échapper un faux numéro de liste
1986\. Une année, pas une étape.

---

Les listes Markdown sont simples tant que leur structure reste visible dans la source. Un tiret et un espace créent une puce. Un nombre suivi d'un point crée une étape. Quatre espaces relient un sous-élément à son parent. [ ] et [x] ajoutent enfin un état de tâche dans les lecteurs qui prennent en charge les listes de tâches.

La règle la plus utile n'est pourtant pas un caractère : choisissez la structure qui exprime réellement votre intention. Utilisez des puces pour regrouper, des numéros pour guider et des cases pour suivre. Lorsque la hiérarchie devient trop profonde, revenez à des titres. Lorsque les tâches deviennent trop nombreuses, passez à une vue Kanban.

Pour aller plus loin, consultez les guides sur les liens Markdown, les images, les tableaux et la mise en forme du texte.

Et pour tester une liste sans créer de fichier, collez sa source dans le lecteur Markdown gratuit de Fude.md.

📌 Télécharger Fude