Як зробити блок, що розгортається, в Markdown:теги details і summary.

Синтаксис

Блок, що розгортається, — звичайний елемент HTML: <details> — контейнер, <summary> — рядок, на який натискають, а все після summary приховане, доки читач не натисне. Відкриває й закриває блок браузер (або веб-подання Markdown-застосунку), тож скриптів немає і новому синтаксису вчитися не треба.

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

Hidden text goes here.

</details>

У закритому вигляді читач бачить маленький трикутник і слова Click to expand. Натискання повертає трикутник і показує текст. Цей самий шаблон використовують README, issues і коментарі до pull request на GitHub для довгих логів і необов'язкових нотаток.

Правило порожнього рядка

Markdown усередині блоку <details> обробляється, лише якщо він відокремлений від HTML-тегів порожнім рядком. Так CommonMark читає HTML-блок: він тягнеться до наступного порожнього рядка й передається як є. Без порожнього рядка ваш **напівжирний** і список лишаться буквальними символами.

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

<details>
<summary>Works</summary>

- this one is a list

</details>

Залиште порожній рядок після </summary> і ще один перед </details>. Сам рядок summary теж HTML, тому використовуйте в ньому <b>bold</b> або <code>code</code>, а не Markdown.

Відкритий за замовчуванням

Додайте атрибут open, щоб блок одразу був розгорнутий. Читач усе одно зможе його згорнути.

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

Node 20 or later.

</details>

Не зловживайте цим: на сторінці, де все відкрите з самого початку, згортання не потрібне, а на сторінці, де все закрите, найкорисніше сховане. Хороше правило: залишайте відповідь на виду, а докази згортайте — довгий вивід, повний конфіг чи список крайніх випадків.

Приклади: код, вкладеність і довгий список

Блоку коду всередині блоку, що розгортається, потрібні порожні рядки, як і будь-якому іншому Markdown:

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

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

</details>

Блоки можна вкладати. Внутрішній за бажання зсуньте, але важливі саме порожні рядки:

<details>
<summary>Troubleshooting</summary>

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

Check the log in the console.

</details>

</details>

Так читач бачить блок, закритий, доки на нього не натиснуть:

Показати повний лог

Усе тут приховане, доки не натиснути на заголовок.

Коли використовувати блок, що розгортається

Згортати варто, коли читач може виконати завдання, не відкриваючи блок. Хороші кандидати — довгий вивід команди, повний файл конфігурації, таблиця параметрів, журнал змін старих версій чи кроки з усунення рідкісних проблем. Коротка нотатка, потрібна більшості читачів, має лишатися на виду.

Блок також зручний, щоб охайно помістити довгі вставлені логи в баг-репорт або опис pull request: читач спершу бачить короткий опис того, що пішло не так, і відкриває лог, лише якщо потрібно. Дайте summary конкретну назву, наприклад Build log (412 lines), щоб читач знав, що всередині, ще до натискання.

Часті помилки

• Немає порожнього рядка. Текст усередині показується як вихідний Markdown. Додайте порожній рядок після summary і перед закривним тегом.
• Markdown у summary. Використовуйте там HTML-теги.
• Немає закривного тегу. Усе, що нижче, лишається всередині блоку.
• Застосунок вирізає HTML. Деякі рендерери видаляють теги, яким не довіряють, і тоді текст просто видно. Якщо блок має працювати всюди, перевірте його там, де його читатимуть.
• Заголовки всередині summary. У більшості застосунків такий заголовок не потрапляє в зміст. Поставте заголовок над блоком.

Згорнутий текст лишається у файлі, тому пошук і diff його бачать, а читач, який ніколи не натискає, — ні. Не ховайте нічого важливого, наприклад попередження.

Як це виглядає

Щоб перевірити блок, відкрийте файл у програмі, яка відображає HTML. DotMD показує <details> як блок, що розгортається натисканням, з відформатованим Markdown усередині, а в DotMD Editor команда Insert → Collapsible Section сама пише теги. Читання безкоштовне.

Питання про блоки, що розгортаються, в Markdown

Інші запитання