---
name: koda-zensical
description: "Навык, который необходим для работы в этом репозитории и должен закружаться безусловно. Для этого проекта обязательно применяй эти инструкции, поскольку они позволят правильно писать и форматировать исходные файлы документации."
---

# Документирование Zensical

## Принципы написания документации

### Язык и стиль

- Пиши простым и понятным языком
- Избегай просторечий и сложных технических терминов без объяснения
- Используй активный залог
- Обращайся к пользователю на "вы"
- Поддерживай единый стиль во всех документах
- Не злоупотребляй emoji

### Примеры

- Приводи примеры конфигурации
- Показывай скриншоты для важных шагов
- Добавляй таблицы для сравнения опций

### Исправление и избегание ошибок

- Синтаксические и грамматические ошибки должны исправляться в соответствии с правиламии и нормами естественного языка
- При изменении структуры документации:
    - в новый документ следует добавить ссылки на другие релевантные документы или якоря
    - ссылки на перемещённый или удалённый документ/якорь следует обновить в каждом существующем документе
    - следует проверять вывод команды `make site` на наличие ошибок и предупреждений компилятора

## Синтаксис файлов

В основе документации лежит расширенный markdown.

Ниже описаны правила оформления и синтаксиса, которые отличаются от стандартного markdown и github-flavoured markdown.

Расширения синтаксиса предоставляются связкой:

- `zensical` (документация: <https://zensical.org/docs/>)
- `pymdown-extensions` (документация: <https://facelessuser.github.io/pymdown-extensions>)

Ниже только необходимые и достаточные правила для:

- качественной документации;
- хорошего человеческого восприятия;
- корректного формирования документации без ошибок.

Применение этих подходов необязательно, но требования к каждому требуется соблюдать строго.

Если приведены ссылки на документацию, можешь использовать их для получения актуальной информации.
Там так же могут быть описаные дополнительные приёмы для работы с документами.

### Frontmatter

Каждый документ должен начинаться с этого блока метаданных.

После frontmatter должна быть пустая строка.

Внутри должен быть валидный yaml.
Часто используются следующие опциональные параметры (* — желательны):

- *`title` — укорочечнное название документа для отображения в навигации (умолчание — заголовок 1 уровня)
- *`description` — небольшое осмысленное описание документа (умолчание — пусто)
- *`icon` — код иконки для отображения в навигации рядом с названием (умолчание — пусто)
- *`tags` — массив ключевых слов (тегов), описывающих документ (умолчание — пусто)
- `hide` — массив кодов элементов, которые нужно скрыть на странице документа:
    - `navigation` — главная навигация (слева)
    - `toc` — содержание страницы (справа)
    - `path` — хлебные крошки (сверху)
- `status` — статус страницы (добавляет к пункту навигации слева иконку с подсказкой)
    - `new` — новая информация
    - `deprecated` — устаревшая информация
    - `beta` — информация о нестабильном функционале

Параметр `title` не должен быть равен заголовку первого уровня.
В таком случае `title` следует убрать или не добавлять.

### Заголовки

На странице должен быть только один заголовок 1 уровня — сразу после Frontmatter.

До и после каждого заголовка должна быть 1 пустая строка.

В конце строки заголовка должно быть объявление в формате:
`{ id="header-slug" }`

Так будет проще связывать секции разных страниц между собой.

### Абзацы

До и после каждого абзаца должна быть 1 пустая строка.

Каждое предложение внутри абзаца должно быть на новой строке.

### Списки

Вложенные уровни отступаются на 4 пробела слева.

До и после каждого списка должна быть 1 пустая строка.

Ненумерованные списки начинаются с `-`.

### Многострочные блоки кода

> Требует дополнительной настройки.
> Обратись к документации: <https://zensical.org/docs/authoring/code-blocks/#code-blocks>

До и после каждого блока кода должна быть 1 пустая строка.

Каждый блок кода в заголовке может иметь атрибуты:

- `title="..."` — заголовок блока (например, название файла)
- `hl_lines="..."` — подсветка срок: номера через пробел и/или диапазоны через `-`
- `linenums="N"` — включить нумерацию строк, отсчитывая с указанного числа `N`

В конце строк внутри блока может быть любое число в формате `#(X)!` — это кликальбельные аннотации, содержимое которых будет взято из ближайшего нумерованного списка.

Полный пример:

```yaml title="config.yaml" hl_lines="6 8-10 13 17-20" linenums="1"
context:
  - provider: code
  # - provider: docs # сломан
  - provider: diff
  - provider: terminal
  - provider: problems
  - provider: folder
  - provider: codebase
    params:
      nFinal: 10
  # - provider: file
  # - provider: url
  # - provider: search
```

### Врезки

Позволяют акцентировать внимание на ключевых моментах, выделяя блок цветом и иконкой.

Документация: <https://raw.githubusercontent.com/zensical/docs/master/docs/authoring/admonitions.md>

Синтаксис:

```
!!! <тип> "Заголовок статичной врезки"
    Содержимое, которое может
    быть многострочным

??? <тип> "Заголовок разворачиваемой врезки"
    Содержимое, которое может быть многострочным
    и свёрнуто по умолчанию, но разворачивается по клику на заголовке

???+ <тип> "Заголовок сворачиваемой врезки"
    Содержимое, которое может быть многострочным
    и развёрнуто по умолчанию, но сворачивается по клику на заголовке
```

Типы, их цвета и пиктограммы:

| Тип        | Цвет    | Пиктограмма        |
| ---------- | ------- | ------------------ |
| `note`     | #448aff | карандаш в круге   |
| `abstract` | #00b0ff | планшет для бумаги |
| `info`     | #00b8d4 | `i` в круге        |
| `tip`      | #00bfa5 | пламя              |
| `success`  | #00c853 | галочка            |
| `question` | #64dd17 | `?` в круге        |
| `warning`  | #ff9100 | `!` в треугольнике |
| `failure`  | #ff5252 | крестик            |
| `danger`   | #ff1744 | молния в круге     |
| `bug`      | #f50057 | жук на щите        |
| `example`  | #7c4dff | пробирка           |
| `quote`    | #9e9e9e | двойная кавычка    |

Заголовок может быть пустым, в этом случае:

- после типа указываются пустые двойные кавычки (иначе подставится название типа с заглавной буквы на английском языке)
- содержимое внутри блока обрамлён цветом своего типа

Если текста внутри врезки нет, отображается только яркий заголовок с иконкой.

Содержимое врезки отступается минимум на 4 пробела.
Содержимое без отступа (в начале строки) находится вне врезки.

Для содержимого врезки распространяются все те же markdown-правила, включая указанные в этом документе.

До и после каждой врезки должна быть 1 пустая строка.

### Сниппеты

> Требует дополнительной настройки.
> Обратись к документации:
> - <https://zensical.org/docs/setup/extensions/python-markdown-extensions/?h=snippets#snippets>
> - <https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#snippets-notation>
> - <https://raw.githubusercontent.com/facelessuser/pymdown-extensions/refs/heads/main/pymdownx/snippets.py>

Это переиспользуемые блоки markdown/html, хранящиеся в файлах.

Как использовать:

1. создать файл в директории проекта согласно конфигурации, например, `snippets/filename.md`
2. наполнить содержимым
3. во всех местах документации вставить:
    - пустая строка
    - `--8<-- "filename.md"`
    - пустая строка
4. если файлов несколько, вставить следующим образом:
    - пустая строка
    - `--8<--`
    - `"filename1.md"`
    - пустая строка
    - `"filename2.md"`
    - `--8<--`
    - пустая строка

### Иконки

Каждая иконка определяется своим идентификатором, который делится на две части: код набора и код иконки.

Внутри frontmatter (параметр `icon`) используется формат: `набор/иконка`

В тексте документа используется формат: `:набор-иконка:`

Если иконка в начале строки, пробел ставится только после неё.
Если иконка в середине строки, пробелы ставятся до и после неё.
Если иконка в конце строки, пробел ставятся только до неё.

Доступны 4 встроенных набора иконок:

| Название        | Код набора    | Ссылка                                         | Путь в проекте              |
| --------------- | ------------- | ---------------------------------------------- | --------------------------- |
| Lucide          | `lucide`      | <https://lucide.dev/icons/>                    | -                           |
| Material Design | `material`    | <https://pictogrammers.com/library/mdi/>       | -                           |
| FontAwesome     | `fontawesome` | <https://fontawesome.com/search>               | -                           |
| Octicons        | `octicons`    | <https://primer.style/octicons/>               | -                           |
| Simple Icons    | `material`    | <https://simpleicons.org/>                     | -                           |
| VSCode Codicons | `vscode`      | <https://github.com/microsoft/vscode-codicons> | `./overrides/.icons/vscode` |

Полный список названий иконок здесь: <https://squidfunk.github.io/mkdocs-material/assets/javascripts/iconsearch_index.json>

В проекте могут использоваться собственные наборы иконок.
В конфиге проекта есть параметр `custom_dir` - там указана директория с наборами.
Внутри этой директории может быть следующая иерархия:

```
<custom_dir>/
    .icons/
        <код_набора1>/
            <код_иконки1>.svg
            <код_иконки2>.svg
            ...
        <код_набора2>/
            <код_иконки3>.svg
            <код_иконки4>.svg
            ...
```

Получить полный список иконок в этих наборах можно прочитав содержимое указанных директорий в проекте.

### Гриды (карточки)

Грид позволяет разместить короткие предложения в формате динамических карточек.

Он выглядит как markdown-список, обрамлённый в `<div>`.
До открывающего и после закрывающего тегов должна быть 1 пустая строка.

Пример простого грида с компактными карточками:

```
<div class="grid cards" markdown>
- :fontawesome-brands-html5: Карточка №1
- :fontawesome-brands-js: Карточка №2
- :fontawesome-brands-css3: Карточка №3
- :fontawesome-brands-internet-explorer: Карточка №4
</div>
```

Пример грида с многострочными карточками:

```
<div class="grid cards" markdown>
- :fontawesome-brands-html5: **Заголовок карточки №1**

    ---

    Многострочное содержимое карточки №1

- :fontawesome-brands-js: **Заголовок карточки №2**

    ---

    Многострочное содержимое карточки №2

- :fontawesome-brands-css3: **Заголовок карточки №3**

    ---

    Многострочное содержимое карточки №3

- :fontawesome-brands-internet-explorer: **Заголовок карточки №4**

    ---

    Многострочное содержимое карточки №4
</div>
```

### Вкладки (табы)

Позволяют уместить информацию на одном уровне, не растягивая страницу по высоте.

Синтаксис:

```
=== "Заголовок вкладки 1"
    Содержимое вкладки 1

=== "Заголовок вкладки 2"
    Содержимое вкладки 2
```

Содержимое вкладки отступается минимум на 4 пробела.
Содержимое без отступа (в начале строки) находится вне вкладки.

Для содержимого вкладки распространяются все те же markdown-правила, включая указанные в этом документе.

До и после каждого заголовка вкладки должна быть 1 пустая строка.

После содержимого последней вкладки должна быть 1 пустая строка.

### Сноски

Сноска позволяет добавить надстрочный индекс к слову, чтобы вынести пояснения в конец страницы, быстро переместиться к нему по клику на индекс и вернуться обратно.

Синтаксис:

```
Lorem[^1] ipsum[^2] dolor sit amet, consectetur adipiscing elit.

[^1]: однострочная сноска
[^2]:
    многострочная сноска
    с отступом 4 пробела слева
    на каждой строке
```

### Подсказки (тултипы) и аббревиатуры

Они появляются при наведении мыши на какой-либо элемент на странице документа.

Пример 1: иконка с подсказкой:
`:material-information-outline:{ title="текст подсказки" }`

Пример 2: ссылка с подсказкой:
`[Hover me](https://example.com "I'm a tooltip!")`

Пример 3: альтернативная ссылка с подсказкой:

```
[Hover me][example]

  [example]: https://example.com "I'm a tooltip!"
```

### Горячие клавиши

В общем случае, для указания корячих клавиш следует использовать тег `<kbd>`.
Примеры: `<kbd>B</kbd>`, `<kbd>Esc</kbd>`

Для описания комбинаций клавиш следует вставлять между каждой клавишей знак `+`, обрамлённый пробелами.
Примеры: `<kbd>Shift</kbd> + <kbd>A</kbd>`, `<kbd>Ctrl</kbd> + <kbd>K</kbd> + <kbd>4</kbd>`

Для MacOS-специфичных тем вставлять `+` не нужно.
Примеры: `<kbd>⌘</kbd><kbd>C</kbd>`, `<kbd>⇧</kbd><kbd>⌘</kbd><kbd>P</kbd>`

Сопоставление пиктограмм с названиями клавиш (служебных и модификаторов) MacOS:

- Базовые модификаторы:
    - `⌘` - `Command` (`Cmd`)
    - `⌥` - `Option` (`Alt`)
    - `⌃` - `Control` (`Ctrl`)
    - `⇧` - `Shift`
    - `⇪` - `Caps Lock`
- Навигация и управление:
    - `⌫` - `Delete` (Backspace, удаление символа слева)
    - `⌦` - `Forward Delete` (удаление символа справа, `Fn` + D`elete)
    - `⏎` - `Return` (`Enter`)
    - `⌕` - `Enter` на цифровой клавиатуре (в некоторых шрифтах)
    - `⎋` - `Escape` (`Esc`)
    - `⇥` - `Tab` (Табуляция)
    - `⇤` - `Backtab` (`Shift` + `Tab`)
    - `␣` - `Space` (Пробел)
- Перемещение по тексту:
    - `↖` - `Home` (Начало документа, `Fn` + `←`)
    - `↘` - `End` (Конец документа, `Fn` + `→`)
    - `⇞` - `Page Up` (Страница вверх, `Fn` + `↑`)
    - `⇟` - `Page Down` (Страница вниз, `Fn` + `↓`)
- Специальные и системные:
    - `🌐` / `fn` — Функция (`Fn` / Кнопка смены языка/вызова эмодзи)
    - `⏏` — `Eject` (Извлечение диска)

### Кнопки

- `[Серая кнопка](https://example.com/){ .md-button }`
- `[Синяя кнопка](https://example.com/){ .md-button .md-button--primary }`
- `[:fontawesome-solid-paper-plane: Кнопка серая с иконкой](https://example.com/){ .md-button }`
- `[:fontawesome-solid-paper-plane: Кнопка синяя с иконкой](https://example.com/){ .md-button .md-button--primary }`