Заметки и каты
Заметка — выделенный блок с важной информацией: примечание, совет, предостережение или запрет. Отдельный вид заметки — кат: блок с заголовком, содержимое которого в веб-просмотре сворачивается. Конструкция пишется один раз в шаблоне и работает во всех каналах вывода: предпросмотр редактора, экспорт в DOCX, PDF и ODT, публикация.
Блок открывается строкой из трех двоеточий с указанием типа и необязательного заголовка, а закрывается отдельной строкой из трех двоеточий.
::: note Необязательный заголовок
Содержимое блока: любой markdown и Jinja.
:::
Результат:
Необязательный заголовок
Содержимое блока: любой markdown и Jinja.
Типы заметок
Тип задает цвет плашки, значок и заголовок по умолчанию:
| Тип | Заголовок по умолчанию | Назначение | Оформление |
|---|---|---|---|
note |
Примечание | дополнительная информация | голубая плашка |
tip |
Совет | рекомендация | зеленая плашка |
warning |
Важно | предостережение | желтая плашка |
alert |
Внимание | ограничение, критичное предупреждение | красная плашка |
cut |
Подробнее | сворачиваемый блок с деталями | заголовок без плашки |
::: tip
Заголовок по умолчанию — «Совет».
:::
::: warning Проверьте перед сохранением
После изменения структуры проверьте документы, которые к ней обращаются.
:::
::: alert Необратимое действие
Восстановить содержимое после этого шага не получится.
:::
Результат:
Совет
Заголовок по умолчанию — «Совет».
Проверьте перед сохранением
После изменения структуры проверьте документы, которые к ней обращаются.
Необратимое действие
Восстановить содержимое после этого шага не получится.
Заголовок блока
Заголовок пишется в открывающей строке после типа. Симметричные кавычки вокруг заголовка снимаются, пустые кавычки убирают заголовок совсем:
| Пишется | Отображается |
|---|---|
::: note |
плашка с заголовком «Примечание» |
::: note Свой заголовок |
плашка с заголовком «Свой заголовок» |
::: note "Свой заголовок" |
то же самое, кавычки снимаются |
::: note "" |
плашка совсем без заголовка |
::: cut |
кат с заголовком «Подробнее» |
::: cut "" |
тоже «Подробнее»: кат без заголовка не бывает |
Сворачиваемый блок
Тип cut убирает с глаз детали, которые нужны не каждому читателю: на виду остается только заголовок, содержимое раскрывается по нажатию.
::: cut Параметры подключения
| Параметр | Значение |
|---|---|
| timeout | 30 c |
| retries | 3 |
:::
Результат:
Параметры подключения
| Параметр | Значение |
|---|---|
| timeout | 30 c |
| retries | 3 |
Сворачивание — свойство просмотра, а не документа
По-настоящему свернутым кат остается только в публикации. В предпросмотре сворачивание работает как удобство чтения шаблона, а в DOCX, PDF и ODT кат всегда развернут: полужирный заголовок и обычные абзацы под ним. Прятать в кат то, что не должно попасть в выгружаемый документ, бессмысленно.
Отображение в разных каналах
| Канал | Плашка (note, tip, warning, alert) | Кат (cut) |
|---|---|---|
| Предпросмотр редактора | цветная плашка с полосой слева и полужирным заголовком | развернут, сворачивается нажатием на заголовок |
| DOCX, PDF, ODT | абзацы со светлой заливкой, цветной полосой слева и внутренними отступами | всегда развернут, без плашки |
| Публикация | плашка с заголовком и значком | свернут, раскрывается нажатием |
| Экспорт MD | конструкция ::: сохраняется как есть |
так же |
В DOCX оформление применяется к конкретным абзацам блока, поэтому стили документа и соседний текст не затрагиваются.
Ограничения
- Jinja внутри блока работает без ограничений: переменные, условия и циклы подставляются до разбора разметки.
- Заголовки разделов (
#,##и далее) внутри заметки не поддерживаются: такой блок останется обычным текстом. - Вложенные заметки не поддерживаются: первый закрывающий
:::завершает блок. - Незакрытый блок и неизвестный тип (например,
::: danger) выводятся обычным текстом и документ не ломают. - Конструкция
:::внутри блока кода — обычный текст: так в документацию вставляются примеры самого синтаксиса. - Таблицы, формулы и списки внутри плашки при экспорте в DOCX выводятся простым текстом, поскольку заливка и боковая полоса рисуются по абзацам. Внутри ката таблицы выгружаются полноценными таблицами.
- Курсив внутри блока задается звездочками (
*курсив*): подчеркивания при экспорте не преобразуются, чтобы не ломать коды видаимя_переменной. - Открывающая строка с отступом в четыре пробела и более считается блоком кода, конструкция не срабатывает.