Come fare una sezione comprimibile in Markdown:i tag details e summary.

La sintassi

Una sezione comprimibile è un semplice elemento HTML: <details> è il contenitore, <summary> è la riga cliccabile e tutto ciò che segue il summary resta nascosto finché chi legge non clicca. L'apertura e la chiusura le gestisce il browser (o la web view dell'app Markdown), quindi non c'è alcuno script né una sintassi in più da imparare.

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

Hidden text goes here.

</details>

Da chiusa, la sezione mostra un piccolo triangolo e le parole Click to expand. Cliccando, il triangolo ruota e compare il testo. È lo stesso schema che usano i README di GitHub, le issue e i commenti delle pull request per log lunghi e note facoltative.

La regola della riga vuota

Il Markdown dentro un blocco <details> viene elaborato solo se è separato dai tag HTML da una riga vuota. È così che CommonMark legge un blocco HTML: arriva fino alla riga vuota successiva e viene passato com'è, come HTML grezzo. Senza la riga vuota, il tuo **grassetto** e il tuo elenco restano caratteri letterali.

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

<details>
<summary>Works</summary>

- this one is a list

</details>

Metti una riga vuota dopo </summary> e un'altra prima di </details>. Anche la riga del summary è HTML, quindi lì usa <b>grassetto</b> o <code>codice</code>, non Markdown.

Aperta di default

Aggiungi l'attributo open per partire con la sezione espansa. Chi legge può comunque chiuderla.

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

Node 20 or later.

</details>

Usalo con parsimonia: in una pagina dove tutto parte aperto non c'è motivo di comprimere, e in una dove tutto parte chiuso le parti utili restano nascoste. Una buona regola è tenere visibile la risposta e ripiegare le prove, come un output lungo, una configurazione completa o un elenco di casi limite.

Esempi: codice, annidamento e un elenco lungo

Un blocco di codice dentro una sezione ha bisogno delle sue righe vuote come qualsiasi altro Markdown:

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

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

</details>

Le sezioni si possono annidare. Rientra quella interna se vuoi, ma ciò che conta sono le righe vuote:

<details>
<summary>Troubleshooting</summary>

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

Check the log in the console.

</details>

</details>

Ecco una sezione come la vede chi legge, chiusa finché non si clicca:

Mostra il log completo

Tutto ciò che c'è qui è nascosto finché non si clicca sul titolo.

Quando usare una sezione comprimibile

Ripiegare vale la pena quando chi legge può finire il compito senza aprire la sezione. Buoni candidati sono l'output lungo di un comando, un file di configurazione completo, una tabella di opzioni, un changelog di vecchie versioni o un elenco di passaggi di risoluzione dei problemi rari. Una breve nota che serve alla maggior parte dei lettori deve restare in vista.

Una sezione è anche un modo ordinato per mettere log lunghi incollati in una segnalazione di bug o nella descrizione di una pull request: chi legge vede prima il riassunto di cosa è andato storto e apre il log solo se serve. Dai al summary un titolo preciso, come Log di build (412 righe), così chi legge sa cosa c'è dentro prima di cliccare.

Errori comuni

• Nessuna riga vuota. Il testo all'interno mostra Markdown grezzo. Aggiungi una riga vuota dopo il summary e prima del tag di chiusura.
• Markdown nel summary. Lì usa i tag HTML.
• Un tag di chiusura mancante. Tutto ciò che sta sotto resta dentro la sezione.
• Un'app che elimina l'HTML. Alcuni renderer rimuovono i tag di cui non si fidano, e allora il testo è semplicemente visibile. Se la sezione deve funzionare ovunque, provala dove verrà letta.
• Titoli dentro il summary. Il titolo non compare nell'indice della maggior parte delle app. Metti il titolo sopra la sezione.

Il testo compresso è comunque nel file, quindi ricerca e diff lo vedono, ma chi non clicca mai no. Non nascondere nulla di essenziale, come un avviso.

Vederla in azione

Per controllare una sezione, apri il file in un lettore che renderizza l'HTML. DotMD mostra <details> come una sezione che si apre con un clic, con il Markdown all'interno formattato, e in DotMD Editor Insert → Collapsible Section scrive i tag per te. La lettura è gratuita.

Domande sulle sezioni comprimibili in Markdown

Altre domande