wip7

2026-07-13 12:30:05 +08:00
parent 7d61aadc5d
commit f25e128299
2023 changed files with 9042 additions and 922 deletions
@@ -0,0 +1,387 @@
+---
+name: koda-zensical
+description: Навык, который необходим для работы в этом репозитории и должен закружаться безусловно. Этот навык содержит инструкции, которые позволят правильно писать и форматировать исходные файлы документации.
+---
+
+# Документирование
+
+## Принципы написания документации
+
+### Язык и стиль
+
+- Пиши простым и понятным языком
+- Избегай просторечий и сложных технических терминов без объяснения
+- Используй активный залог
+- Обращайся к пользователю на "вы"
+- Поддерживай единый стиль во всех документах
+- Не злоупотребляй 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 пустая строка.
+
+Ненумерованные списки начинаются с `-`.
+
+### Многострочные блоки кода
+
+До и после каждого блока кода должна быть 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 #(2)!
+  - provider: terminal
+  - provider: problems
+  - provider: folder
+  - provider: codebase
+    params:
+      nFinal: 10
+  # - provider: file
+  # - provider: url
+  # - provider: search #(1)!
+```
+
+    1. Подсказка 1
+    2. **Подсказка** 2
+
+### Врезки
+
+Позволяют акцентировать внимание на ключевых моментах, выделяя блок цветом и иконкой.
+
+Документация: <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 пустая строка.
+
+### Сниппеты
+
+Это переиспользуемые блоки markdown/html, хранящиеся в файлах.
+
+- Директория: `snippets` в корне проекта
+- Документация: <https://raw.githubusercontent.com/facelessuser/pymdown-extensions/refs/heads/main/pymdownx/snippets.py>
+
+Как использовать:
+
+1. создать файл с директории
+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>
+
+Получить полный список иконок в этих наборах можно прочитав содержимое указанных директорий в проекте.
+
+### Гриды (карточки)
+
+Грид позволяет разместить короткие предложения в формате динамических карточек.
+
+Он выглядит как 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 }`