Как сделать раскрывающийся блок в 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

Другие вопросы