388 lines
19 KiB
Markdown
388 lines
19 KiB
Markdown
---
|
||
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 }`
|