Comment ajouter une case à cocher en Markdown :syntaxe et exemples de listes de tâches.

La syntaxe des listes de tâches Markdown

Une liste de tâches est une liste ordinaire dont les éléments commencent par un marqueur de case. La recette comporte trois parties :

1. Un marqueur de liste

   Un tiret, un astérisque ou un plus, suivi d’une espace : -. Un élément numéroté comme 1. fonctionne aussi.

2. Une case entre crochets

   [ ] avec une espace au milieu est une case vide. [x] est une case cochée ; un [X] majuscule compte aussi. Rien d’autre ne se met entre les crochets.

3. Une espace, puis le texte

   Sans espace après ], la ligne reste du texte brut avec des crochets.

- [x] Draft the spec
- [x] Add the edge cases
- [ ] Get a review
- [ ] Hand it to the agent

Voici ce que voit le lecteur :

• Draft the spec
• Add the edge cases
• Get a review
• Hand it to the agent

Cases à cocher imbriquées

Indentez une tâche sous une autre pour créer une sous-tâche. Deux espaces suffisent dans la plupart des moteurs de rendu ; quatre sont le plus sûr :

- [ ] Release 2.0
    - [x] Update the changelog
    - [ ] Tag the build
    - [ ] Announce it
- [ ] Plan 2.1

Vous pouvez mêler des tâches et de simples puces dans la même liste, et placer un paragraphe, du code ou une citation sous une tâche en l’indentant pour l’aligner sur le texte de la tâche. La case parente ne se coche pas toute seule quand ses enfants sont terminés ; c’est à vous de la cocher.

Où les cases à cocher Markdown s’affichent

• GitHub affiche les listes de tâches en cases à cocher dans les fichiers Markdown, les issues, les pull requests et les commentaires. Dans une issue ou une pull request, vous pouvez cocher une case sur la page et GitHub modifie le texte à votre place.
• Les applications Markdown qui suivent GFM les affichent aussi. Dans DotMD, elles apparaissent comme des cases dans le lecteur. Elles y sont en lecture seule : pour en cocher une, modifiez la ligne et changez [ ] en [x].
• Les analyseurs minimaux qui ne connaissent que le Markdown d’origine ou CommonMark affichent le texte tel quel, avec les crochets. Cela se lit encore comme une liste de choses à faire, mais pas en cases.

Si vous utilisez DotMD Editor, appuyer sur Enter à la fin d’une tâche démarre la suivante avec un - [ ] vide, pour que vous puissiez continuer à saisir des éléments.

Une coche Markdown sans liste de tâches

Pour une coche dans un tableau ou une phrase, et non dans une liste, tapez le caractère lui-même. Les symboles Unicode sont du texte : ils s’affichent dans toutes les applications Markdown :

GitHub accepte aussi les codes courts d’emoji comme :white_check_mark:. C’est une fonction de GitHub : dans une autre application, ils peuvent s’afficher en texte brut ; préférez donc le caractère lui-même si le fichier sera lu ailleurs.

Listes de tâches dans les plans et les specs

Les listes de tâches ne servent pas qu’aux applications de to-do. Un plan ou une spec écrit en Markdown se termine souvent par une checklist de ce qui reste à faire, et chaque étape se relit facilement sur sa propre ligne :

## Tasks
- [x] Add the settings screen
- [ ] Write the migration
- [ ] Update the tests
- [ ] Update the docs

Limitez chaque tâche à une action qui peut être terminée et vérifiée. Utilisez un titre pour chaque groupe et n’imbriquez des sous-tâches que si elles appartiennent à un même parent.

Pourquoi une liste de tâches affiche des crochets au lieu de cases

• Pas d’espace après le crochet : - [x]Done n’est pas une tâche. Écrivez - [x] Done.
• Des espaces dans les crochets : [ ] avec deux espaces, ou [ x ], est du texte brut.
• Pas de marqueur de liste : une ligne qui commence par [ ] seul n’est pas un élément de liste.
• Un texte qui commence par une parenthèse. La documentation de GitHub dit d’échapper la parenthèse : écrivez - [ ] \(Optional) Test it.
• Le moteur de rendu ne gère pas GFM. Vous voyez alors les crochets, quoi que vous tapiez.

Pour voir à quoi ressemble un plan avec des tâches, ouvrez le fichier dans DotMD, où la lecture est gratuite. Les specs et les plans s’écrivent souvent en listes de tâches, et les cases rendent une longue liste facile à parcourir.

Questions sur les cases à cocher Markdown

Plus de questions