Comment faire une section repliable en Markdown :les balises details et summary.

La syntaxe

Une section repliable est un simple élément HTML : <details> est le conteneur, <summary> la ligne cliquable, et tout ce qui suit le summary reste masqué jusqu’au clic du lecteur. C’est le navigateur (ou la vue web de l’application Markdown) qui ouvre et ferme, sans script et sans syntaxe supplémentaire à apprendre.

<details>
<summary>Click to expand</summary>

Hidden text goes here.

</details>

Fermée, elle montre au lecteur un petit triangle et les mots Click to expand. Un clic fait pivoter le triangle et affiche le texte. C’est le même motif que celui des README, des issues et des commentaires de pull request sur GitHub pour les longs journaux et les notes facultatives.

La règle de la ligne vide

Le Markdown à l’intérieur d’un bloc <details> n’est interprété que s’il est séparé des balises HTML par une ligne vide. C’est ainsi que CommonMark lit un bloc HTML : il va jusqu’à la prochaine ligne vide et passe tel quel comme HTML brut. Sans ligne vide, votre **bold** et votre liste restent des caractères littéraux.

<details>
<summary>Broken</summary>
- this list is not turned into a list
</details>

<details>
<summary>Works</summary>

- this one is a list

</details>

Mettez une ligne vide après </summary> et une autre avant </details>. La ligne du summary est elle aussi du HTML : utilisez-y <b>bold</b> ou <code>code</code>, pas du Markdown.

Ouverte par défaut

Ajoutez l’attribut open pour que la section démarre dépliée. Le lecteur peut toujours la replier.

<details open>
<summary>Prerequisites</summary>

Node 20 or later.

</details>

Servez-vous-en avec parcimonie : sur une page où tout démarre ouvert, rien ne justifie de replier, et sur une page où tout démarre fermé, les parties utiles sont cachées. Une bonne règle : gardez la réponse visible et repliez les preuves, comme une longue sortie, une configuration complète ou une liste de cas limites.

Exemples : du code, de l’imbrication et une longue liste

Un bloc de code dans une section a besoin de ses lignes vides comme tout autre Markdown :

<details>
<summary>Full config</summary>

```json
{ "retries": 3, "timeout": 30 }
```

</details>

Les sections peuvent s’imbriquer. Indentez celle de l’intérieur si vous voulez, mais ce sont les lignes vides qui comptent :

<details>
<summary>Troubleshooting</summary>

<details>
<summary>The app does not start</summary>

Check the log in the console.

</details>

</details>

Voici une section telle que la voit le lecteur, fermée jusqu’au clic :

Show the full log

Everything here is hidden until the title is clicked.

Quand utiliser une section repliable

Replier vaut la peine quand le lecteur peut finir sa tâche sans ouvrir la section. De bons candidats : une longue sortie de commande, un fichier de configuration complet, un tableau d’options, un historique des anciennes versions ou une liste d’étapes de dépannage pour des problèmes rares. Une courte note dont la plupart des lecteurs ont besoin doit rester visible.

Une section est aussi une façon propre de mettre de longs journaux collés dans un rapport de bug ou une description de pull request : le lecteur voit d’abord le résumé de ce qui a mal tourné et n’ouvre le journal que s’il en a besoin. Donnez au summary un titre précis, comme Build log (412 lines), pour que le lecteur sache ce qu’il y a dedans avant de cliquer.

Erreurs courantes

• Pas de ligne vide. Le texte à l’intérieur affiche du Markdown brut. Ajoutez une ligne vide après le summary et avant la balise fermante.
• Du Markdown dans le summary. Utilisez-y des balises HTML.
• Une balise fermante manquante. Tout ce qui suit reste dans la section.
• Une application qui supprime le HTML. Certains moteurs de rendu retirent les balises auxquelles ils ne font pas confiance, et le texte devient alors simplement visible. Si la section doit marcher partout, testez-la là où elle sera lue.
• Des titres dans le summary. Le titre n’apparaît pas dans le plan de la plupart des applications. Mettez plutôt le titre au-dessus de la section.

Le texte replié est toujours dans le fichier : la recherche et les diffs le voient, mais pas un lecteur qui ne clique jamais. Ne cachez rien d’essentiel, comme un avertissement.

Le voir fonctionner

Pour vérifier une section, ouvrez le fichier dans un lecteur qui interprète le HTML. DotMD affiche <details> comme une section qui s’ouvre au clic, avec le Markdown à l’intérieur mis en forme, et dans DotMD Editor Insert → Collapsible Section écrit les balises à votre place. La lecture est gratuite.

Questions sur les sections repliables en Markdown

Plus de questions