Jak zrobić zwijaną sekcję w Markdown:znaczniki details i summary.

Składnia

Zwijana sekcja to zwykły element HTML: <details> to kontener, <summary> to klikalna linia, a wszystko po summary jest ukryte, dopóki czytelnik nie kliknie. Otwieranie i zamykanie robi przeglądarka (lub widok webowy aplikacji Markdown), więc nie ma skryptu ani dodatkowej składni do nauki.

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

Hidden text goes here.

</details>

Gdy sekcja jest zamknięta, czytelnik widzi mały trójkąt i słowa Click to expand. Kliknięcie obraca trójkąt i pokazuje tekst. Tego samego wzorca używają README na GitHubie, zgłoszenia i komentarze pull requestów dla długich logów i opcjonalnych notatek.

Zasada pustej linii

Markdown wewnątrz bloku <details> jest przetwarzany tylko wtedy, gdy oddziela go od znaczników HTML pusta linia. Tak CommonMark czyta blok HTML: ciągnie się do następnej pustej linii i jest przekazywany jako surowy HTML. Bez pustej linii twoje **pogrubienie** i lista zostają dosłownymi znakami.

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

<details>
<summary>Works</summary>

- this one is a list

</details>

Wstaw pustą linię po </summary> i kolejną przed </details>. Sama linia summary to też HTML, więc użyj tam <b>pogrubienia</b> lub <code>kodu</code>, a nie Markdown.

Otwarta domyślnie

Dodaj atrybut open, by zacząć z rozwiniętą sekcją. Czytelnik nadal może ją zwinąć.

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

Node 20 or later.

</details>

Używaj go oszczędnie: na stronie, na której wszystko zaczyna się otwarte, nie ma powodu do zwijania, a na stronie, na której wszystko zaczyna się zamknięte, użyteczne części są ukryte. Dobra zasada: odpowiedź trzymaj na widoku, a dowody schowaj, jak długi wynik, pełną konfigurację lub listę przypadków brzegowych.

Przykłady: kod, zagnieżdżanie i długa lista

Blok kodu wewnątrz sekcji potrzebuje pustych linii jak każdy inny Markdown:

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

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

</details>

Sekcje można zagnieżdżać. Wewnętrzną możesz wciąć, ale liczą się puste linie:

<details>
<summary>Troubleshooting</summary>

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

Check the log in the console.

</details>

</details>

Oto sekcja tak, jak widzi ją czytelnik, zamknięta do kliknięcia:

Pokaż pełny log

Wszystko tutaj jest ukryte, dopóki nie klikniesz tytułu.

Kiedy używać zwijanej sekcji

Zwijanie się opłaca, gdy czytelnik może skończyć zadanie bez otwierania sekcji. Dobrzy kandydaci to długi wynik polecenia, pełny plik konfiguracyjny, tabela opcji, dziennik zmian starych wersji lub lista kroków rozwiązywania rzadkich problemów. Krótka uwaga, której potrzebuje większość czytelników, powinna zostać na widoku.

Sekcja to też schludny sposób na wklejenie długich logów do zgłoszenia błędu lub opisu pull requestu: czytelnik najpierw widzi streszczenie tego, co poszło nie tak, a log otwiera tylko, gdy potrzebuje. Daj summary konkretny tytuł, na przykład Log kompilacji (412 linii), żeby czytelnik wiedział, co jest w środku, zanim kliknie.

Częste błędy

• Brak pustej linii. Tekst w środku pokazuje surowy Markdown. Dodaj pustą linię po summary i przed znacznikiem zamykającym.
• Markdown w summary. Użyj tam znaczników HTML.
• Brak znacznika zamykającego. Wszystko poniżej zostaje wewnątrz sekcji.
• Aplikacja usuwająca HTML. Niektóre renderery usuwają znaczniki, którym nie ufają, i wtedy tekst jest po prostu widoczny. Jeśli sekcja musi działać wszędzie, przetestuj ją tam, gdzie będzie czytana.
• Nagłówki wewnątrz summary. Nagłówek nie pojawia się w spisie treści większości aplikacji. Umieść nagłówek nad sekcją.

Zwinięty tekst nadal jest w pliku, więc wyszukiwanie i diffy go widzą, ale czytelnik, który nigdy nie kliknie, nie. Nie ukrywaj niczego istotnego, jak ostrzeżenie.

Zobacz, jak działa

Aby sprawdzić sekcję, otwórz plik w czytniku, który renderuje HTML. DotMD pokazuje <details> jako sekcję otwieraną kliknięciem, z sformatowanym Markdown w środku, a w DotMD Editor Insert → Collapsible Section zapisuje znaczniki za ciebie. Czytanie jest bezpłatne.

Pytania o zwijane sekcje w Markdown

Więcej pytań