Jak udělat rozbalovací sekci v Markdownu:značky details a summary.

Syntaxe

Rozbalovací sekce je obyčejný HTML prvek: <details> je kontejner, <summary> je řádek, na který se klikne, a vše za summary je skryté, dokud čtenář neklikne. Otevírání a zavírání obstará prohlížeč (nebo webové zobrazení aplikace pro Markdown), takže nepotřebujete skript ani se učit novou syntaxi.

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

Hidden text goes here.

</details>

Zavřená sekce ukazuje malý trojúhelník a slova Click to expand. Klik otočí trojúhelník a ukáže text. Stejný vzor používají README, issues a komentáře k pull requestům na GitHubu pro dlouhé logy a nepovinné poznámky.

Pravidlo prázdného řádku

Markdown uvnitř bloku <details> se zpracuje, jen když je od HTML značek oddělený prázdným řádkem. Tak CommonMark čte HTML blok: běží do dalšího prázdného řádku a předá se jako holé HTML. Bez prázdného řádku zůstane váš **tučný text** i seznam jako doslovné znaky.

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

<details>
<summary>Works</summary>

- this one is a list

</details>

Dejte prázdný řádek za </summary> a další před </details>. Samotný řádek summary je také HTML, takže tam používejte <b>bold</b> nebo <code>code</code>, ne Markdown.

Otevřená ve výchozím stavu

Přidejte atribut open, aby sekce začínala rozbalená. Čtenář ji může stále sbalit.

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

Node 20 or later.

</details>

Používejte to střídmě: stránka, na které začíná vše otevřené, nemá důvod být sbalitelná, a stránka, na které je vše zavřené, skrývá užitečné části. Dobré pravidlo: odpověď nechte viditelnou a sbalte důkazy, například dlouhý výstup, celou konfiguraci nebo seznam okrajových případů.

Příklady: kód, vnoření a dlouhý seznam

Blok kódu uvnitř sekce potřebuje prázdné řádky jako jakýkoli jiný Markdown:

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

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

</details>

Sekce lze vnořovat. Vnitřní můžete odsadit, ale rozhodují prázdné řádky:

<details>
<summary>Troubleshooting</summary>

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

Check the log in the console.

</details>

</details>

Takhle vypadá sekce čtenáři, zavřená, dokud na ni neklikne:

Zobrazit celý log

Vše tady je skryté, dokud se neklikne na nadpis.

Kdy použít rozbalovací sekci

Sbalení se vyplatí, když čtenář dokáže úkol dokončit, aniž by sekci otevřel. Dobří kandidáti jsou dlouhý výstup příkazu, celý konfigurační soubor, tabulka voleb, changelog starých verzí nebo seznam kroků pro řešení vzácných potíží. Krátká poznámka, kterou potřebuje většina čtenářů, má zůstat na očích.

Sekce je také úhledný způsob, jak dát dlouhé vložené logy do hlášení chyby nebo popisu pull requestu: čtenář nejdřív vidí shrnutí, co se pokazilo, a log otevře, jen když ho potřebuje. Dejte summary konkrétní název, například Build log (412 lines), aby čtenář věděl, co je uvnitř, ještě před kliknutím.

Časté chyby

• Chybí prázdný řádek. Text uvnitř se zobrazí jako holý Markdown. Přidejte prázdný řádek za summary a před zavírací značku.
• Markdown v summary. Používejte tam HTML značky.
• Chybí zavírací značka. Vše pod ní zůstane uvnitř sekce.
• Aplikace odstraňuje HTML. Některé renderery značky, kterým nedůvěřují, odstraní a text je pak prostě vidět. Pokud má sekce fungovat všude, vyzkoušejte ji tam, kde se bude číst.
• Nadpisy uvnitř summary. Nadpis se ve většině aplikací neobjeví v osnově. Dejte nadpis nad sekci.

Sbalený text je pořád v souboru, takže ho vidí vyhledávání a diffy, ale čtenář, který nikdy neklikne, ne. Neskrývejte nic podstatného, například varování.

Jak to vypadá v praxi

Chcete-li sekci vyzkoušet, otevřete soubor v čtečce, která vykresluje HTML. DotMD zobrazuje <details> jako sekci, která se rozbalí kliknutím, s naformátovaným Markdownem uvnitř, a v DotMD Editoru příkaz Insert → Collapsible Section značky napíše za vás. Čtení je zdarma.

Otázky k rozbalovacím sekcím v Markdownu

Další otázky