---
metadata:
  - name: generator
    content: Diplodoc Platform v5.62.0
style:
  - _assets/styles/custom.css
  - _assets/fonts-golos-text.css
  - _assets/styles/hero-gradient.css
  - _assets/styles/hero-decoration.css
script:
  - _assets/scripts/latex-trust.js
description: Руководство пользователя (новая версия) - Заметки и каты
title: Заметки и каты
vcsPath: sintaksis-shablonov/zametki-i-katy.md
alternate:
  - href: sintaksis-shablonov/zametki-i-katy.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    rel: describedby
theme: _assets/style/theme.css
---

# Заметки и каты

Заметка — выделенный блок с важной информацией: примечание, совет, предостережение или запрет. Отдельный вид заметки — кат: блок с заголовком, содержимое которого в веб-просмотре сворачивается. Конструкция пишется один раз в шаблоне и работает во всех каналах вывода: предпросмотр редактора, экспорт в DOCX, PDF и ODT, публикация.

Блок открывается строкой из трех двоеточий с указанием типа и необязательного заголовка, а закрывается отдельной строкой из трех двоеточий.
```jinja
::: note Необязательный заголовок
Содержимое блока: любой markdown и Jinja.
:::
```
**Результат:**


{% note info "Необязательный заголовок" %}

Содержимое блока: любой markdown и Jinja.

{% endnote %}


## Типы заметок
Тип задает цвет плашки, значок и заголовок по умолчанию:

| Тип | Заголовок по умолчанию | Назначение | Оформление |
|---|---|---|---|
| `note` | Примечание | дополнительная информация | голубая плашка |
| `tip` | Совет | рекомендация | зеленая плашка |
| `warning` | Важно | предостережение | желтая плашка |
| `alert` | Внимание | ограничение, критичное предупреждение | красная плашка |
| `cut` | Подробнее | сворачиваемый блок с деталями | заголовок без плашки |

```jinja
::: tip
Заголовок по умолчанию — «Совет».
:::

::: warning Проверьте перед сохранением
После изменения структуры проверьте документы, которые к ней обращаются.
:::

::: alert Необратимое действие
Восстановить содержимое после этого шага не получится.
:::
```
**Результат:**


{% note tip "Совет" %}

Заголовок по умолчанию — «Совет».

{% endnote %}



{% note warning "Проверьте перед сохранением" %}

После изменения структуры проверьте документы, которые к ней обращаются.

{% endnote %}



{% note alert "Необратимое действие" %}

Восстановить содержимое после этого шага не получится.

{% endnote %}


## Заголовок блока
Заголовок пишется в открывающей строке после типа. Симметричные кавычки вокруг заголовка снимаются, пустые кавычки убирают заголовок совсем:

| Пишется | Отображается |
|---|---|
| `::: note` | плашка с заголовком «Примечание» |
| `::: note Свой заголовок` | плашка с заголовком «Свой заголовок» |
| `::: note "Свой заголовок"` | то же самое, кавычки снимаются |
| `::: note ""` | плашка совсем без заголовка |
| `::: cut` | кат с заголовком «Подробнее» |
| `::: cut ""` | тоже «Подробнее»: кат без заголовка не бывает |

## Сворачиваемый блок
Тип `cut` убирает с глаз детали, которые нужны не каждому читателю: на виду остается только заголовок, содержимое раскрывается по нажатию.
```jinja
::: cut Параметры подключения
| Параметр | Значение |
|---|---|
| timeout | 30 c |
| retries | 3 |
:::
```
**Результат:**


{% cut "Параметры подключения" %}

| Параметр | Значение |
|---|---|
| timeout | 30 c |
| retries | 3 |

{% endcut %}



{% note warning "Сворачивание — свойство просмотра, а не документа" %}

По-настоящему свернутым кат остается только в публикации. В предпросмотре сворачивание работает как удобство чтения шаблона, а в DOCX, PDF и ODT кат всегда развернут: полужирный заголовок и обычные абзацы под ним. Прятать в кат то, что не должно попасть в выгружаемый документ, бессмысленно.

{% endnote %}


## Отображение в разных каналах
| Канал | Плашка (note, tip, warning, alert) | Кат (cut) |
|---|---|---|
| Предпросмотр редактора | цветная плашка с полосой слева и полужирным заголовком | развернут, сворачивается нажатием на заголовок |
| DOCX, PDF, ODT | абзацы со светлой заливкой, цветной полосой слева и внутренними отступами | всегда развернут, без плашки |
| Публикация | плашка с заголовком и значком | свернут, раскрывается нажатием |
| Экспорт MD | конструкция `:::` сохраняется как есть | так же |

В DOCX оформление применяется к конкретным абзацам блока, поэтому стили документа и соседний текст не затрагиваются.

## Ограничения
- Jinja внутри блока работает без ограничений: переменные, условия и циклы подставляются до разбора разметки.
- Заголовки разделов (`#`, `##` и далее) внутри заметки не поддерживаются: такой блок останется обычным текстом.
- Вложенные заметки не поддерживаются: первый закрывающий `:::` завершает блок.
- Незакрытый блок и неизвестный тип (например, `::: danger`) выводятся обычным текстом и документ не ломают.
- Конструкция `:::` внутри блока кода — обычный текст: так в документацию вставляются примеры самого синтаксиса.
- Таблицы, формулы и списки внутри плашки при экспорте в DOCX выводятся простым текстом, поскольку заливка и боковая полоса рисуются по абзацам. Внутри ката таблицы выгружаются полноценными таблицами.
- Курсив внутри блока задается звездочками (`*курсив*`): подчеркивания при экспорте не преобразуются, чтобы не ломать коды вида `имя_переменной`.
- Открывающая строка с отступом в четыре пробела и более считается блоком кода, конструкция не срабатывает.