Перевод на zensical и актуализация
This commit is contained in:
@@ -0,0 +1,384 @@
|
|||||||
|
---
|
||||||
|
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 пустая строка.
|
||||||
|
|
||||||
|
### Абзацы
|
||||||
|
|
||||||
|
До и после каждого абзаца должна быть 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 }`
|
||||||
+3
-2
@@ -1,3 +1,4 @@
|
|||||||
/.cache
|
/.cache/
|
||||||
/site
|
/site/
|
||||||
|
/__pycache__/
|
||||||
.DS_Store
|
.DS_Store
|
||||||
|
|||||||
+25
@@ -0,0 +1,25 @@
|
|||||||
|
- Всегда используй навык koda-zensical
|
||||||
|
- Всегда перечитывай файлы перед каждым изменением - пользователь уже мог внести изменения
|
||||||
|
- При изменениях структуры проекта всегда актуализируй AGENTS.md
|
||||||
|
- |
|
||||||
|
В структуре навигации файла `zensical.toml` всегда должен присутствовать закомментированный раздел `Debug`.
|
||||||
|
Это отладочные страницы с примерами, которые не должны попасть в итоговую документацию.
|
||||||
|
Этот раздел раскомментируется вручную по необходимости.
|
||||||
|
- |
|
||||||
|
Для отладки используй команду `make site`.
|
||||||
|
В выводе команды могу быть предупреждения и ошибки в следующем формате:
|
||||||
|
|
||||||
|
```
|
||||||
|
Warning: page does not exist
|
||||||
|
╭─[ test.md:695:10 ]
|
||||||
|
│
|
||||||
|
695 │ - [Edit](../edit/how-to-use-it.md) — редактирование кода
|
||||||
|
│ ────────────┬───────────
|
||||||
|
│ ╰───────────── page does not exist
|
||||||
|
─────╯
|
||||||
|
```
|
||||||
|
что означает буквально следующее: "в файле content/test.md в строке 695 в позиции 10 есть ссылка на несуществующую страницу."
|
||||||
|
Эти предупреждения надо всегда исправлять.
|
||||||
|
|
||||||
|
- При изменениях структуры проекта и только при корректной сборке (без предупреждений и ошибок) всегда актуализируй `./AGENTS.md`
|
||||||
|
- При доработке или расширении функционала этого проекта или синтаксиса всегда актуализируй скилл `./.agents/skills/koda-zensical`
|
||||||
Vendored
+5
@@ -0,0 +1,5 @@
|
|||||||
|
{
|
||||||
|
"recommendations": [
|
||||||
|
"0x10.mkdocs-material-preview"
|
||||||
|
]
|
||||||
|
}
|
||||||
Vendored
+5
@@ -0,0 +1,5 @@
|
|||||||
|
{
|
||||||
|
"files.associations": {
|
||||||
|
"*.md": "python-markdown"
|
||||||
|
}
|
||||||
|
}
|
||||||
Vendored
+22
@@ -0,0 +1,22 @@
|
|||||||
|
{
|
||||||
|
// See https://go.microsoft.com/fwlink/?LinkId=733558
|
||||||
|
// for the documentation about the tasks.json format
|
||||||
|
"version": "2.0.0",
|
||||||
|
"tasks": [
|
||||||
|
{
|
||||||
|
"label": "Живой предпросмотр (localhost:8000)",
|
||||||
|
"type": "shell",
|
||||||
|
"command": "make live"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"label": "Собрать статический сайт (./site)",
|
||||||
|
"type": "shell",
|
||||||
|
"command": "make site"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"label": "Собрать docker-образ со стат. сайтом",
|
||||||
|
"type": "shell",
|
||||||
|
"command": "make image"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
@@ -0,0 +1,129 @@
|
|||||||
|
# KODA.md — контекст проекта
|
||||||
|
|
||||||
|
## Обзор проекта
|
||||||
|
|
||||||
|
Бойлерплейт для документации на базе [Zensical](https://zensical.org) — системы документации, построенной на MkDocs Material.
|
||||||
|
Проект предназначен для быстрого старта документации к любому продукту или сервису: от локальной разработки с live-предпросмотром до сборки Docker-образа со статическим сайтом на nginx.
|
||||||
|
|
||||||
|
### Технологии
|
||||||
|
|
||||||
|
- **Zensical** — движок документации (форк MkDocs Material)
|
||||||
|
- **Docker** — контейнерная сборка и деплой
|
||||||
|
- **nginx:alpine** — раздача статического сайта
|
||||||
|
- **Python** — кастомный плагин `inline_badges.py` (inline-бейджи через HTML-комментарии)
|
||||||
|
- **TOML** — конфигурация проекта (`zensical.toml`)
|
||||||
|
|
||||||
|
### Архитектура
|
||||||
|
|
||||||
|
Проект использует двухэтапную сборку Docker-образа:
|
||||||
|
|
||||||
|
1. **Builder** (`zensical/zensical:latest`) — собирает статический сайт из Markdown-файлов в `content/`
|
||||||
|
2. **Runtime** (`nginx:alpine`) — раздаёт готовый статический сайт на порту 80
|
||||||
|
|
||||||
|
Вся разработка ведётся через Docker — локальная установка Zensical не требуется.
|
||||||
|
|
||||||
|
## Структура проекта
|
||||||
|
|
||||||
|
```
|
||||||
|
content/ — исходные страницы документации (.md)
|
||||||
|
index.md — главная страница
|
||||||
|
part1/ — пример раздела с вложенными страницами
|
||||||
|
sandbox.md — песочница с примерами синтаксиса (отладочная)
|
||||||
|
vscode-icons.md — справочник VSCode-иконок (отладочная)
|
||||||
|
_asseets/ — assets (изображения, стили, скрипты)
|
||||||
|
snippets/ — переиспользуемые блоки markdown
|
||||||
|
abbr.md — аббревиатуры
|
||||||
|
coming_soon.md — заглушка «скоро появится»
|
||||||
|
config_file_path.md — пример сниппета с путями конфигурации
|
||||||
|
overrides/ — кастомизация темы Zensical
|
||||||
|
.icons/ — кастомные наборы иконок (vscode/)
|
||||||
|
zensical.toml — конфигурация проекта (тема, навигация, расширения)
|
||||||
|
inline_badges.py — Python-плагин для inline-бейджей
|
||||||
|
Dockerfile — многоэтапная сборка: zensical build → nginx
|
||||||
|
Makefile — команды для разработки и деплоя
|
||||||
|
CONTRIBUTING.md — правила контрибуции
|
||||||
|
.editorconfig — настройки редактора (отступы, кодировка, переносы)
|
||||||
|
.dockerignore — исключения для Docker-контекста
|
||||||
|
.kodarules — правила для AI-ассистента
|
||||||
|
```
|
||||||
|
|
||||||
|
## Сборка и запуск
|
||||||
|
|
||||||
|
Все команды выполняются через `make` (требуется установленный Docker).
|
||||||
|
|
||||||
|
| Команда | Описание |
|
||||||
|
| ------------ | --------------------------------------------------------------------- |
|
||||||
|
| `make live` | Запуск в режиме живой перезагрузки на `http://localhost:8000` |
|
||||||
|
| `make site` | Генерация статического сайта с валидацией ссылок и якорей |
|
||||||
|
| `make image` | Сборка Docker-образа `harbor.example.com/boilerplate-docs:latest` |
|
||||||
|
| `make run` | Запуск контейнера из образа на `http://localhost:8001` |
|
||||||
|
| `make push` | Загрузка Docker-образа в реестр `harbor.example.com` |
|
||||||
|
| `make help` | Справка по командам (цель по умолчанию) |
|
||||||
|
|
||||||
|
### Валидация
|
||||||
|
|
||||||
|
При сборке (`make site`) включена валидация:
|
||||||
|
|
||||||
|
- битые ссылки (`invalid_links = true`)
|
||||||
|
- битые якоря (`invalid_link_anchors = true`)
|
||||||
|
|
||||||
|
Предупреждения и ошибки валидации необходимо исправлять перед отправкой изменений.
|
||||||
|
|
||||||
|
## Конфигурация
|
||||||
|
|
||||||
|
### zensical.toml
|
||||||
|
|
||||||
|
Основной конфигурационный файл. Ключевые настройки:
|
||||||
|
|
||||||
|
- **Документация:** `content/`, вывод в `site/`
|
||||||
|
- **Тема:** Material с поддержкой светлой/тёмной тем, шрифты Inter / JetBrains Mono
|
||||||
|
- **Навигация:** табы, секции, хлебные крошки, кнопка «наверх», прошлый/следующий документ
|
||||||
|
- **Расширения Markdown:** admonition, tabs, superfences, snippets, footnotes, emoji, highlight, inline badges
|
||||||
|
- **Иконки:** Lucide, Material Design, FontAwesome, Octicons, Simple Icons, VSCode Codicons (кастомные)
|
||||||
|
- **Теги:** настроены иконки для HTML, JS, CSS, VSCode, JetBrains, CLI, AI/LLM
|
||||||
|
- **Социальные ссылки:** Telegram, YouTube, GitHub (в футере)
|
||||||
|
- **Debug-раздел:** закомментированный блок в `nav` для отладочных страниц (`sandbox.md`, `vscode-icons.md`)
|
||||||
|
|
||||||
|
### inline_badges.py
|
||||||
|
|
||||||
|
Кастомный Python-плагин для Markdown. Преобразует HTML-комментарии в бейджи:
|
||||||
|
|
||||||
|
- `<!-- md:version 8.5.0 -->` — бейдж версии с иконкой `material/tag-outline`
|
||||||
|
- `<!-- md:default true -->` — бейдж значения по умолчанию с иконкой `material/water`
|
||||||
|
- `<!-- md:flag experimental -->` — бейдж экспериментального функционала с иконкой `material/test-tube`
|
||||||
|
|
||||||
|
## Правила разработки
|
||||||
|
|
||||||
|
### Стиль и форматирование
|
||||||
|
|
||||||
|
- Кодировка UTF-8, переносы строк LF
|
||||||
|
- Отступы: 4 пробела (2 для YAML/YML, табы для Makefile)
|
||||||
|
- В Markdown-файлах завершающие пробелы не обрезаются
|
||||||
|
- В остальных файлах — обрезаются
|
||||||
|
- В конце файла — пустая строка
|
||||||
|
|
||||||
|
### Документация
|
||||||
|
|
||||||
|
- Язык документации — русский
|
||||||
|
- Обращение к пользователю на «вы»
|
||||||
|
- Простой и понятный язык, активный залог
|
||||||
|
- Каждый документ начинается с frontmatter (YAML с метаданными)
|
||||||
|
- На странице — один заголовок 1 уровня
|
||||||
|
- До и после заголовков, абзацев, списков, блоков кода, врезок — пустая строка
|
||||||
|
- Вложенные уровни списков отступаются на 4 пробела
|
||||||
|
- Ненумерованные списки начинаются с `-`
|
||||||
|
- Подробные правила синтаксиса — в скилле `.agents/skills/koda-zensical`
|
||||||
|
|
||||||
|
### Отладка
|
||||||
|
|
||||||
|
- Для отладки использовать `make site` и проверять вывод на предупреждения
|
||||||
|
- Debug-страницы (`sandbox.md`, `vscode-icons.md`) не должны попадать в навигацию — раздел `Debug` в `zensical.toml` закомментирован
|
||||||
|
- Раскомментирование `Debug` выполняется вручную по необходимости
|
||||||
|
|
||||||
|
### Контрибуция
|
||||||
|
|
||||||
|
Подробные правила — в [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||||
|
|
||||||
|
## Лицензия
|
||||||
|
|
||||||
|
MIT License
|
||||||
+16
-3
@@ -1,8 +1,21 @@
|
|||||||
FROM squidfunk/mkdocs-material AS builder
|
FROM zensical/zensical:latest AS builder
|
||||||
|
ENV PYTHONPATH=/docs
|
||||||
COPY . /docs
|
COPY . /docs
|
||||||
RUN mkdocs build
|
RUN zensical build --clean
|
||||||
|
|
||||||
|
FROM nginx:alpine AS boilerplate-docs
|
||||||
|
|
||||||
|
# LABEL org.opencontainers.image.revision="c76960ef08be04f397b72702eca4166c7b783176"
|
||||||
|
# LABEL org.opencontainers.image.description="Documentation for our services and products"
|
||||||
|
# LABEL org.opencontainers.image.url="https://example.com"
|
||||||
|
# LABEL org.opencontainers.image.vendor="Boilerplate"
|
||||||
|
# LABEL org.opencontainers.image.documentation="https://example.com"
|
||||||
|
# LABEL org.opencontainers.image.version="v0.0.46"
|
||||||
|
# LABEL org.opencontainers.image.created="2026-06-21T18:47:29.228Z"
|
||||||
|
# LABEL org.opencontainers.image.licenses="MIT"
|
||||||
|
# LABEL org.opencontainers.image.title="BoilerplateDocs"
|
||||||
|
# LABEL org.opencontainers.image.source=""
|
||||||
|
|
||||||
FROM nginx:alpine AS iptv-docs
|
|
||||||
COPY --from=builder /docs/site /usr/share/nginx/html
|
COPY --from=builder /docs/site /usr/share/nginx/html
|
||||||
WORKDIR /usr/share/nginx/html
|
WORKDIR /usr/share/nginx/html
|
||||||
USER root
|
USER root
|
||||||
|
|||||||
@@ -1,47 +1,54 @@
|
|||||||
.DEFAULT_GOAL := help
|
.DEFAULT_GOAL := help
|
||||||
.PHONY: live site image run help
|
.PHONY: live site image push run help
|
||||||
|
|
||||||
## live: Run mkdocs with live-reloading (localhost:3000)
|
## live = Run zensical with live-reloading on http://localhost:8000
|
||||||
live:
|
live:
|
||||||
@echo "Wait until container starts and open http://localhost:3000 to see live preview"
|
@echo "*** Wait until container starts and open http://localhost:8000 to see live preview"
|
||||||
@docker run \
|
@docker stop boilerplate-docs-dev 2>/dev/null; \
|
||||||
--pull always \
|
docker run \
|
||||||
--rm \
|
--rm \
|
||||||
--interactive \
|
--interactive \
|
||||||
--tty \
|
--tty \
|
||||||
--publish 3000:8000 \
|
--env PYTHONPATH=/docs \
|
||||||
|
--publish 8000:8000 \
|
||||||
--volume ${PWD}:/docs \
|
--volume ${PWD}:/docs \
|
||||||
--name my-project-docs-dev \
|
--name boilerplate-docs-dev \
|
||||||
squidfunk/mkdocs-material:9.6.20
|
zensical/zensical:latest
|
||||||
|
|
||||||
## site: Build local static site
|
## site = Build a local static site
|
||||||
site:
|
site:
|
||||||
@echo "Wait until mkdocs finish"
|
@echo "*** Wait until zensical finish"
|
||||||
@docker run \
|
@docker stop boilerplate-docs-dev 2>/dev/null; \
|
||||||
|
docker run \
|
||||||
--pull always \
|
--pull always \
|
||||||
--rm \
|
--rm \
|
||||||
--interactive \
|
--env PYTHONPATH=/docs \
|
||||||
--tty \
|
|
||||||
--volume ${PWD}:/docs \
|
--volume ${PWD}:/docs \
|
||||||
--name my-project-docs-dev \
|
--name boilerplate-docs-dev \
|
||||||
squidfunk/mkdocs-material:9.6.20 build
|
zensical/zensical:latest \
|
||||||
|
build \
|
||||||
|
--clean
|
||||||
|
|
||||||
## image: Build docker image
|
## image = Build a docker image
|
||||||
image:
|
image:
|
||||||
@docker build \
|
@docker build --tag harbor.example.com/boilerplate-docs:latest .
|
||||||
--tag my-project-docs-dev:latest \
|
|
||||||
.
|
|
||||||
|
|
||||||
## run: Run docker image (localhost:3001)
|
## run = Run docker container from image built with `make image` on http://localhost:8001
|
||||||
run:
|
run:
|
||||||
@echo "Wait until container starts and open http://localhost:3001 to see ready static website"
|
@echo "*** Wait until container starts and open http://localhost:8001 to see ready static website"
|
||||||
@docker run \
|
@docker stop boilerplate-docs 2>/dev/null; \
|
||||||
|
docker run \
|
||||||
--rm \
|
--rm \
|
||||||
--publish 3001:80 \
|
--publish 8001:80 \
|
||||||
--name my-project-docs-dev \
|
--name boilerplate-docs \
|
||||||
my-project-docs-dev:latest
|
harbor.example.com/boilerplate-docs:latest
|
||||||
|
|
||||||
## help: Show this message and exit
|
## push = Push docker image built with `make image` to harbor.example.com
|
||||||
|
push:
|
||||||
|
@docker login harbor.example.com; \
|
||||||
|
docker push harbor.example.com/boilerplate-docs:latest
|
||||||
|
|
||||||
|
## help = Show this message and exit (default)
|
||||||
help: Makefile
|
help: Makefile
|
||||||
@echo "Available recipes:"
|
@echo "Available recipes:"
|
||||||
@sed -n 's/^##/ /p' $< | column -t -s ':'
|
@sed -n 's/^##/ /p' $< | column -t -s '='
|
||||||
|
|||||||
@@ -1,7 +1,54 @@
|
|||||||
# Пример документации к проекту
|
# Документация к проекту
|
||||||
|
|
||||||
* `make live` -- запуск в режиме живой перезагрузки для отладки
|
Бойлерплейт для документации на базе [Zensical](https://zensical.org) — системы документации, построенной на MkDocs Material.
|
||||||
* `make site` -- генерация статического сайта
|
|
||||||
* `make image` -- генерация docker-образа
|
## Возможности
|
||||||
* `make run` -- запуск контейнера из docker-образа
|
|
||||||
* `make help` -- справка по командам
|
- Live-предпросмотр с автоматической перезагрузкой
|
||||||
|
- Сборка статического сайта в Docker-образ на базе nginx
|
||||||
|
- Светлая и тёмная темы оформления
|
||||||
|
- Расширенный Markdown: врезки, вкладки, гриды, сноски, иконки
|
||||||
|
- Валидация ссылок и якорей при сборке
|
||||||
|
- Поддержка сниппетов и переиспользуемых блоков
|
||||||
|
- Кастомные inline-бейджи через `inline_badges.py`
|
||||||
|
|
||||||
|
## Структура проекта
|
||||||
|
|
||||||
|
```
|
||||||
|
content/ — исходные страницы документации (.md)
|
||||||
|
snippets/ — переиспользуемые блоки markdown
|
||||||
|
overrides/ — кастомизация темы: иконки, шаблоны, стили
|
||||||
|
zensical.toml — конфигурация проекта
|
||||||
|
inline_badges.py — плагин inline-бейджей
|
||||||
|
Dockerfile — многоэтапная сборка: zensical build → nginx
|
||||||
|
Makefile — команды для разработки и деплоя
|
||||||
|
```
|
||||||
|
|
||||||
|
## Быстрый старт
|
||||||
|
|
||||||
|
### Требования
|
||||||
|
|
||||||
|
- [Docker](https://docs.docker.com/get-docker/)
|
||||||
|
|
||||||
|
### Команды
|
||||||
|
|
||||||
|
| Команда | Описание |
|
||||||
|
| ------------ | --------------------------------------------------------------- |
|
||||||
|
| `make live` | Запуск в режиме живой перезагрузки на `http://localhost:8000` |
|
||||||
|
| `make site` | Генерация статического сайта (с валидацией ссылок и якорей) |
|
||||||
|
| `make image` | Сборка Docker-образа |
|
||||||
|
| `make run` | Запуск контейнера на `http://localhost:8001` |
|
||||||
|
| `make push` | Загрузка Docker-образа в реестр |
|
||||||
|
| `make help` | Справка по командам (по умолчанию) |
|
||||||
|
|
||||||
|
## Разработка
|
||||||
|
|
||||||
|
Для локальной отладки используйте `make live` — откройте `http://localhost:8000` после запуска контейнера.
|
||||||
|
|
||||||
|
Для проверки сборки без предупреждений используйте `make site`.
|
||||||
|
|
||||||
|
Подробности о форматировании и стиле — в [CONTRIBUTING.md](CONTRIBUTING.md).
|
||||||
|
|
||||||
|
## Лицензия
|
||||||
|
|
||||||
|
MIT License
|
||||||
|
|||||||
@@ -1,130 +0,0 @@
|
|||||||
---
|
|
||||||
title: Глоссарий терминов
|
|
||||||
icon: material/format-text
|
|
||||||
---
|
|
||||||
|
|
||||||
# Глоссарий терминов
|
|
||||||
|
|
||||||
Справочник терминов, используемых в документации Koda.
|
|
||||||
|
|
||||||
## A
|
|
||||||
|
|
||||||
**Agent (Агент)** — режим работы Koda, в котором AI самостоятельно выполняет многошаговые задачи, используя различные инструменты.
|
|
||||||
|
|
||||||
**API Key (API-ключ)** — уникальный ключ для доступа к API провайдера моделей (OpenAI, Anthropic и др.).
|
|
||||||
|
|
||||||
**Autocomplete (Автодополнение)** — режим автоматического предложения продолжения кода при наборе.
|
|
||||||
|
|
||||||
## C
|
|
||||||
|
|
||||||
**Chat (Чат)** — режим диалога с AI-моделью для решения задач, объяснения кода и получения рекомендаций.
|
|
||||||
|
|
||||||
**Completion** — см. Autocomplete.
|
|
||||||
|
|
||||||
**Config (Конфигурация)** — файл настроек Koda (`config.yaml`), определяющий модели, провайдеров и параметры.
|
|
||||||
|
|
||||||
**Context (Контекст)** — информация, которую Koda использует для генерации ответов (файлы, код, документация).
|
|
||||||
|
|
||||||
**Context Provider (Контекстный провайдер)** — компонент, автоматически добавляющий релевантную информацию в запросы через символ <kbd>@</kbd> (file, code, docs, codebase, diff, terminal и др.). Подробнее в [Контекст-провайдеры](context-providers.md).
|
|
||||||
|
|
||||||
## D
|
|
||||||
|
|
||||||
**Diff (Дифф)** — разница между двумя версиями файла, показывающая изменения.
|
|
||||||
|
|
||||||
## E
|
|
||||||
|
|
||||||
**Edit (Редактирование)** — режим изменения выделенного кода по инструкции пользователя.
|
|
||||||
|
|
||||||
**Embeddings (Эмбеддинги)** — векторные представления текста для поиска по семантическому сходству.
|
|
||||||
|
|
||||||
## F
|
|
||||||
|
|
||||||
**FIM (Fill-In-Middle)** — техника автодополнения, когда модель заполняет текст между префиксом и суффиксом.
|
|
||||||
|
|
||||||
## I
|
|
||||||
|
|
||||||
**Indexing (Индексация)** — процесс анализа и векторизации кодовой базы или документации для быстрого поиска.
|
|
||||||
|
|
||||||
## L
|
|
||||||
|
|
||||||
**LLM (Large Language Model)** — большая языковая модель, используемая для генерации текста и кода.
|
|
||||||
|
|
||||||
## M
|
|
||||||
|
|
||||||
**Model (Модель)** — AI-модель, используемая для генерации ответов (GPT-4, Claude, Llama и др.).
|
|
||||||
|
|
||||||
**Model Role (Роль модели)** — назначение модели в Koda (chat, edit, agent, autocomplete, embed, rerank).
|
|
||||||
|
|
||||||
## P
|
|
||||||
|
|
||||||
**Provider (Провайдер)** — сервис, предоставляющий доступ к AI-моделям (OpenAI, Anthropic, Ollama и др.).
|
|
||||||
|
|
||||||
**Prompt (Промпт)** — текстовый запрос к AI-модели.
|
|
||||||
|
|
||||||
## R
|
|
||||||
|
|
||||||
**RAG (Retrieval-Augmented Generation)** — техника генерации ответов с использованием поиска по внешней базе знаний.
|
|
||||||
|
|
||||||
**Retrieval (Поиск)** — режим поиска по документации и другим источникам информации.
|
|
||||||
|
|
||||||
**Roles (Роли)** — см. Model Role.
|
|
||||||
|
|
||||||
## S
|
|
||||||
|
|
||||||
**Session (Сессия)** — отдельный диалог в чате Koda со своей историей и контекстом.
|
|
||||||
|
|
||||||
**Session History (История сессий)** — список всех предыдущих сессий с возможностью поиска, переключения и удаления.
|
|
||||||
|
|
||||||
**Session Metadata (Метаданные сессии)** — информация о сессии: ID, заголовок, дата создания, режим работы, рабочая директория.
|
|
||||||
|
|
||||||
**Session Storage (Хранилище сессий)** — место сохранения данных сессий (локальные файлы `~/.koda/sessions/` или серверное хранилище).
|
|
||||||
|
|
||||||
**Summarization (Суммаризация)** — процесс сжатия длинной истории диалога в краткое содержание для экономии токенов.
|
|
||||||
|
|
||||||
**SummaryMarker (Маркер суммаризации)** — визуальный индикатор в истории чата, показывающий где была применена суммаризация.
|
|
||||||
|
|
||||||
**Auto-Summarize (Автосуммаризация)** — автоматическая суммаризация при достижении 75% использования контекста (только Agent режим).
|
|
||||||
|
|
||||||
**Skill (Навык)** — переиспользуемый набор инструкций для AI-модели, хранящийся в отдельном файле.
|
|
||||||
|
|
||||||
**Slash Command (Slash-команда)** — специальная команда, начинающаяся с <kbd>@</kbd> (например, /share, /commit, /summarize).
|
|
||||||
|
|
||||||
## T
|
|
||||||
|
|
||||||
**Token (Токен)** — единица измерения длины текста для AI-моделей (примерно ¾ слова).
|
|
||||||
|
|
||||||
**Tool (Инструмент)** — действие, которое агент может выполнить (читать файл, редактировать код, запускать команду).
|
|
||||||
|
|
||||||
## V
|
|
||||||
|
|
||||||
:material-microsoft-visual-studio-code: **VS Code** — Visual Studio Code, среда разработки от Microsoft.
|
|
||||||
|
|
||||||
## W
|
|
||||||
|
|
||||||
**Workspace (Рабочая область)** — проект или директория, открытая в IDE.
|
|
||||||
|
|
||||||
## Ё
|
|
||||||
|
|
||||||
**Ёфикация** — использование буквы "ё" вместо "е" в русских текстах документации.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Сокращения
|
|
||||||
|
|
||||||
| Сокращение | Расшифровка |
|
|
||||||
|------------|-------------|
|
|
||||||
| AI | Artificial Intelligence (Искусственный интеллект) |
|
|
||||||
| API | Application Programming Interface |
|
|
||||||
| IDE | Integrated Development Environment |
|
|
||||||
| LLM | Large Language Model |
|
|
||||||
| [RAG] | Retrieval-Augmented Generation |
|
|
||||||
| :material-microsoft-visual-studio-code: VS Code | Visual Studio Code |
|
|
||||||
| FIM | Fill-In-Middle |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Дополнительные ресурсы
|
|
||||||
|
|
||||||
- [Основная документация](README.md)
|
|
||||||
- [Режимы работы](modes.md)
|
|
||||||
- [Инструменты агента](agent-tools.md)
|
|
||||||
@@ -0,0 +1,284 @@
|
|||||||
|
# Песочница
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Мелочёвка
|
||||||
|
|
||||||
|
=== "Frontmatter"
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
title: My Page
|
||||||
|
description: Some page description
|
||||||
|
icon: material/star
|
||||||
|
tags: [tag1, tag2]
|
||||||
|
hide: [navigation, toc, path]
|
||||||
|
status: new
|
||||||
|
#status: deprecated
|
||||||
|
#status: beta
|
||||||
|
---
|
||||||
|
|
||||||
|
# My Super-Duper Page
|
||||||
|
|
||||||
|
# Markdown content goes here
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "Бейджи"
|
||||||
|
|
||||||
|
<!-- md:version 8.5.0 --> <!-- md:default true --> <!-- md:flag experimental -->
|
||||||
|
|
||||||
|
=== "Тултипы"
|
||||||
|
|
||||||
|
:material-information-outline:{ title="текст подсказки" }
|
||||||
|
|
||||||
|
[Hover me 1](https://example.com "I'm first tooltip!")
|
||||||
|
|
||||||
|
[Hover me 2][example]
|
||||||
|
|
||||||
|
[example]: https://example.com "I'm second tooltip!"
|
||||||
|
|
||||||
|
=== "Кнопки"
|
||||||
|
|
||||||
|
[Серая кнопка](https://example.com/){ .md-button }
|
||||||
|
|
||||||
|
[Синяя кнопка](https://example.com/){ .md-button .md-button--primary }
|
||||||
|
|
||||||
|
[:fontawesome-solid-paper-plane: Кнопка серая с иконкой и подсказкой](https://example.com/){ .md-button title="текст подсказки 2" }
|
||||||
|
|
||||||
|
[:fontawesome-solid-paper-plane: Кнопка синяя с иконкой](https://example.com/){ .md-button .md-button--primary }
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
=== "Простой блок"
|
||||||
|
|
||||||
|
```python
|
||||||
|
def _render_icon(shortcode: str, md) -> str:
|
||||||
|
emoji_pattern = md.inlinePatterns.get("emoji")
|
||||||
|
if emoji_pattern is None:
|
||||||
|
return escape(shortcode)
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "С аннотациями"
|
||||||
|
|
||||||
|
```python
|
||||||
|
def _render_icon(shortcode: str, md) -> str: #(1)!
|
||||||
|
emoji_pattern = md.inlinePatterns.get("emoji") #(2)!
|
||||||
|
if emoji_pattern is None:
|
||||||
|
return escape(shortcode) #(3)!
|
||||||
|
```
|
||||||
|
|
||||||
|
1. сигнатура функции
|
||||||
|
2. инициализация переменной
|
||||||
|
3. возврат результата
|
||||||
|
|
||||||
|
=== "С заголовком"
|
||||||
|
|
||||||
|
```python title="example.py"
|
||||||
|
def _render_icon(shortcode: str, md) -> str:
|
||||||
|
emoji_pattern = md.inlinePatterns.get("emoji")
|
||||||
|
if emoji_pattern is None:
|
||||||
|
return escape(shortcode)
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "С нумерацией с 5"
|
||||||
|
|
||||||
|
```python linenums="5"
|
||||||
|
def _render_icon(shortcode: str, md) -> str:
|
||||||
|
emoji_pattern = md.inlinePatterns.get("emoji")
|
||||||
|
if emoji_pattern is None:
|
||||||
|
return escape(shortcode)
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "С выделением"
|
||||||
|
|
||||||
|
```python linenums="1" hl_lines="2-5 8 9 22"
|
||||||
|
def _render_icon(shortcode: str, md) -> str:
|
||||||
|
try:
|
||||||
|
emoji_pattern = md.inlinePatterns["emoji"]
|
||||||
|
except KeyError:
|
||||||
|
return escape(shortcode)
|
||||||
|
|
||||||
|
icon = emoji_pattern.emoji_index["emoji"].get(shortcode)
|
||||||
|
if icon is None:
|
||||||
|
return escape(shortcode)
|
||||||
|
|
||||||
|
element = emoji_pattern.generator(
|
||||||
|
emoji_pattern.emoji_index["name"],
|
||||||
|
shortcode,
|
||||||
|
None,
|
||||||
|
None,
|
||||||
|
shortcode,
|
||||||
|
"",
|
||||||
|
icon.get("category", ""),
|
||||||
|
emoji_pattern.options,
|
||||||
|
md,
|
||||||
|
)
|
||||||
|
return tostring(element, encoding="unicode", method="html")
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Врезки
|
||||||
|
|
||||||
|
=== "Полные"
|
||||||
|
|
||||||
|
!!! note "Заголовок статичной врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
!!! abstract "Заголовок статичной врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
!!! info "Заголовок статичной врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
!!! tip "Заголовок статичной врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
!!! success "Заголовок статичной врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
!!! question "Заголовок статичной врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
!!! warning "Заголовок статичной врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
!!! failure "Заголовок статичной врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
!!! danger "Заголовок статичной врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
!!! bug "Заголовок статичной врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
!!! example "Заголовок статичной врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
!!! quote "Заголовок статичной врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
=== "Свёрнутые"
|
||||||
|
|
||||||
|
??? note "Заголовок свёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
??? abstract "Заголовок свёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
??? info "Заголовок свёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
??? tip "Заголовок свёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
??? success "Заголовок свёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
??? question "Заголовок свёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
??? warning "Заголовок свёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
??? failure "Заголовок свёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
??? danger "Заголовок свёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
??? bug "Заголовок свёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
??? example "Заголовок свёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
??? quote "Заголовок свёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
=== "Сворачиваемые"
|
||||||
|
|
||||||
|
???+ note "Заголовок развёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
???+ abstract "Заголовок развёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
???+ info "Заголовок развёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
???+ tip "Заголовок развёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
???+ success "Заголовок развёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
???+ question "Заголовок развёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
???+ warning "Заголовок развёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
???+ failure "Заголовок развёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
???+ danger "Заголовок развёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
???+ bug "Заголовок развёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
???+ example "Заголовок развёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
???+ quote "Заголовок развёрнутой врезки"
|
||||||
|
Содержимое, которое может
|
||||||
|
быть многострочным
|
||||||
|
|
||||||
|
=== "Короткие"
|
||||||
|
|
||||||
|
!!! note
|
||||||
|
Дефолтный заголовок
|
||||||
|
|
||||||
|
!!! abstract ""
|
||||||
|
Пустой заголовок
|
||||||
|
|
||||||
|
!!! info "Пустое содержимое"
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
@@ -1,14 +0,0 @@
|
|||||||
---
|
|
||||||
title: Теги
|
|
||||||
icon: material/tag-text
|
|
||||||
---
|
|
||||||
|
|
||||||
# Теги документации
|
|
||||||
|
|
||||||
Здесь перечислены все теги, которые встречаются на страницах документации.
|
|
||||||
|
|
||||||
Нажмите на ссылку для перехода к странице, которая содержит тег.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
<!-- material/tags -->
|
|
||||||
+549
-548
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,49 @@
|
|||||||
|
from __future__ import annotations
|
||||||
|
|
||||||
|
import re
|
||||||
|
from html import escape
|
||||||
|
|
||||||
|
from markdown.extensions import Extension
|
||||||
|
from markdown.preprocessors import Preprocessor
|
||||||
|
|
||||||
|
SHORTCODE_RE = re.compile(r"<!--\s*md:(version|default|flag)\s*(.*?)\s*-->", re.I)
|
||||||
|
|
||||||
|
class BadgePreprocessor(Preprocessor):
|
||||||
|
def run(self, lines: list[str]) -> list[str]:
|
||||||
|
return [SHORTCODE_RE.sub(self._replace, line) for line in lines]
|
||||||
|
|
||||||
|
def _replace(self, match: re.Match[str]) -> str:
|
||||||
|
kind, args = match.groups()
|
||||||
|
args = args.strip()
|
||||||
|
|
||||||
|
if kind == "version":
|
||||||
|
return _badge(":material-tag-outline:", escape(args))
|
||||||
|
|
||||||
|
if kind == "default":
|
||||||
|
value = escape(args or "none")
|
||||||
|
return _badge(":material-water:", f"<code>{value}</code>")
|
||||||
|
|
||||||
|
if kind == "flag" and args == "experimental":
|
||||||
|
return _badge(":material-test-tube:")
|
||||||
|
|
||||||
|
return match.group(0)
|
||||||
|
|
||||||
|
|
||||||
|
# Формирует HTML-разметку бейджа. Иконки остаются Zensical-шорткодами
|
||||||
|
# и рендерятся штатным `pymdownx.emoji` на следующем этапе обработки Markdown.
|
||||||
|
def _badge(icon: str, text: str = "") -> str:
|
||||||
|
return "".join([
|
||||||
|
'<span class="mdx-badge">',
|
||||||
|
f'<span class="mdx-badge__icon">{icon}</span>',
|
||||||
|
*([f'<span class="mdx-badge__text">{text}</span>'] if text else []),
|
||||||
|
'</span>',
|
||||||
|
])
|
||||||
|
|
||||||
|
|
||||||
|
class InlineBadgeExtension(Extension):
|
||||||
|
def extendMarkdown(self, md):
|
||||||
|
md.preprocessors.register(BadgePreprocessor(md), "inline_badges", 175)
|
||||||
|
|
||||||
|
|
||||||
|
def makeExtension(**kwargs):
|
||||||
|
return InlineBadgeExtension(**kwargs)
|
||||||
-142
@@ -1,142 +0,0 @@
|
|||||||
site_name: Документация
|
|
||||||
site_description: Описание проекта и его компонентов
|
|
||||||
site_author: Иван Иванов
|
|
||||||
copyright: Иван Иванов © 2026, MIT License
|
|
||||||
|
|
||||||
repo_name: Репозиторий
|
|
||||||
repo_url: https://git.axenov.dev/anthony/mkdocs-boilerplate
|
|
||||||
edit_uri: src/branch/master/content/
|
|
||||||
remote_branch: master
|
|
||||||
|
|
||||||
docs_dir: ./content
|
|
||||||
use_directory_urls: false
|
|
||||||
watch:
|
|
||||||
- content
|
|
||||||
- snippets
|
|
||||||
extra_css:
|
|
||||||
- css/custom.css
|
|
||||||
# extra_javascript:
|
|
||||||
# - https://unpkg.com/ionicons@7.1.0/dist/ionicons/ionicons.js
|
|
||||||
|
|
||||||
extra:
|
|
||||||
homepage: /docs
|
|
||||||
logo: assets/img/favicon/logo.png
|
|
||||||
favicon: assets/img/favicon/logo.png
|
|
||||||
social:
|
|
||||||
- name: Telegram
|
|
||||||
icon: simple/telegram
|
|
||||||
link: https://t.me/
|
|
||||||
- name: YouTube
|
|
||||||
icon: simple/youtube
|
|
||||||
link: https://www.youtube.com/
|
|
||||||
alternate:
|
|
||||||
- name: Русский
|
|
||||||
link: /
|
|
||||||
lang: ru
|
|
||||||
- name: English
|
|
||||||
link: /en/
|
|
||||||
lang: en
|
|
||||||
|
|
||||||
theme:
|
|
||||||
name: 'material'
|
|
||||||
language: ru
|
|
||||||
custom_dir: overrides
|
|
||||||
features:
|
|
||||||
- content.action.edit
|
|
||||||
- content.tabs.link
|
|
||||||
- navigation.footer
|
|
||||||
- navigation.indexes
|
|
||||||
- navigation.path
|
|
||||||
- navigation.sections
|
|
||||||
# - navigation.expand
|
|
||||||
- navigation.tabs
|
|
||||||
- navigation.top
|
|
||||||
- navigation.tracking
|
|
||||||
- search.suggest
|
|
||||||
- toc.follow
|
|
||||||
icon:
|
|
||||||
repo: simple/github
|
|
||||||
edit: material/pencil
|
|
||||||
view: material/eye
|
|
||||||
annotation: material/chevron-right-circle
|
|
||||||
palette:
|
|
||||||
# Автотема
|
|
||||||
- media: "(prefers-color-scheme)"
|
|
||||||
toggle:
|
|
||||||
icon: material/brightness-auto
|
|
||||||
name: Включить тёмную тему
|
|
||||||
# Тёмная тема
|
|
||||||
- scheme: slate
|
|
||||||
media: "(prefers-color-scheme: light)"
|
|
||||||
accent: teal
|
|
||||||
primary: black
|
|
||||||
toggle:
|
|
||||||
name: Включить светлую тему
|
|
||||||
icon: material/weather-sunny
|
|
||||||
# Светлая тема
|
|
||||||
- scheme: default
|
|
||||||
media: "(prefers-color-scheme: dark)"
|
|
||||||
accent: teal
|
|
||||||
primary: teal
|
|
||||||
toggle:
|
|
||||||
name: Предпочесть системную тему
|
|
||||||
icon: material/weather-night
|
|
||||||
|
|
||||||
plugins:
|
|
||||||
- minify:
|
|
||||||
minify_html: true
|
|
||||||
- tags:
|
|
||||||
listings: true
|
|
||||||
tags_hierarchy: true
|
|
||||||
tags_hierarchy_separator: /
|
|
||||||
tags_name_property: keywords
|
|
||||||
# shadow: true
|
|
||||||
export: true
|
|
||||||
listings_toc: true
|
|
||||||
- social:
|
|
||||||
cards_layout_options:
|
|
||||||
background_color: teal
|
|
||||||
background_image: null
|
|
||||||
- search:
|
|
||||||
separator: '[\s\-\.]+'
|
|
||||||
# indexing: 'full'
|
|
||||||
|
|
||||||
validation:
|
|
||||||
omitted_files: warn
|
|
||||||
absolute_links: warn
|
|
||||||
unrecognized_links: warn
|
|
||||||
anchors: warn
|
|
||||||
|
|
||||||
markdown_extensions:
|
|
||||||
- admonition
|
|
||||||
- attr_list
|
|
||||||
- md_in_html
|
|
||||||
- footnotes
|
|
||||||
- pymdownx.details
|
|
||||||
- pymdownx.superfences
|
|
||||||
- pymdownx.tasklist:
|
|
||||||
clickable_checkbox: false
|
|
||||||
- pymdownx.snippets:
|
|
||||||
base_path: snippets
|
|
||||||
# auto_append:
|
|
||||||
# - abbr.md
|
|
||||||
- toc:
|
|
||||||
permalink: true
|
|
||||||
- pymdownx.tabbed:
|
|
||||||
alternate_style: true
|
|
||||||
- pymdownx.emoji:
|
|
||||||
emoji_index: !!python/name:material.extensions.emoji.twemoji
|
|
||||||
emoji_generator: !!python/name:material.extensions.emoji.to_svg
|
|
||||||
options:
|
|
||||||
custom_icons:
|
|
||||||
- overrides/.icons
|
|
||||||
|
|
||||||
nav:
|
|
||||||
- index.md
|
|
||||||
- "Раздел 1":
|
|
||||||
- part1/page1.md
|
|
||||||
- part1/page2.md
|
|
||||||
- "Доп. сведения":
|
|
||||||
- vscode-icons.md # debug
|
|
||||||
- glossary.md
|
|
||||||
- tags.md
|
|
||||||
@@ -1,4 +1,4 @@
|
|||||||
Расположение файла конфигурации:
|
Расположение файла конфигурации:
|
||||||
|
|
||||||
- :fontawesome-brands-windows: Windows: `%USERPROFILE%/.koda/config.yaml`
|
- :fontawesome-brands-windows: Windows: `%USERPROFILE%/.example/config.yaml`
|
||||||
- :simple-linux: Linux / :simple-apple: MacOS: `$HOME/.koda/config.yaml`
|
- :simple-linux: Linux / :simple-apple: MacOS: `$HOME/.example/config.yaml`
|
||||||
|
|||||||
+211
@@ -0,0 +1,211 @@
|
|||||||
|
# https://zensical.org/docs/setup/basics
|
||||||
|
|
||||||
|
[project]
|
||||||
|
site_name = "Документация"
|
||||||
|
site_url = "https://example.com"
|
||||||
|
site_description = "Описание проекта и его компонентов"
|
||||||
|
site_author = "Иван Иванов"
|
||||||
|
copyright = "Иван Иванов © 2026, MIT License"
|
||||||
|
# copyright = "Иван Иванов © 2026, MIT License | <a href="#__consent">Настройки cookie</a>"
|
||||||
|
# repo_url = "https://git.axenov.dev/anthony/zensical-boilerplate"
|
||||||
|
# repo_name = "anthony/zensical-boilerplate"
|
||||||
|
# edit_uri = "src/branch/master/content/"
|
||||||
|
|
||||||
|
docs_dir = "./content"
|
||||||
|
site_dir = "./site"
|
||||||
|
use_directory_urls = false
|
||||||
|
dev_addr = "localhost:8000"
|
||||||
|
watch = ["content", "snippets"]
|
||||||
|
extra_css = ["_css/extra.css"]
|
||||||
|
# extra_javascript = [
|
||||||
|
# "_js/extra.js",
|
||||||
|
# "https://unpkg.com/ionicons@7.1.0/dist/ionicons/ionicons.js",
|
||||||
|
# ]
|
||||||
|
|
||||||
|
nav = [
|
||||||
|
"index.md",
|
||||||
|
{"Раздел 1" = [
|
||||||
|
"part1/page1.md",
|
||||||
|
"part1/page2.md",
|
||||||
|
]},
|
||||||
|
# {"Debug" = [
|
||||||
|
# "vscode-icons.md",
|
||||||
|
# "sandbox.md",
|
||||||
|
# ]},
|
||||||
|
]
|
||||||
|
|
||||||
|
[project.validation] # валидация контента при сборке
|
||||||
|
invalid_links = true # битые ссылки
|
||||||
|
invalid_link_anchors = true # битые якоря
|
||||||
|
|
||||||
|
[project.extra]
|
||||||
|
homepage = "/index.html" # ссылка на логотипе
|
||||||
|
generator = false # убрать из футера ссылку на Zensical
|
||||||
|
|
||||||
|
# [project.extra.consent] # предупреждение о куках
|
||||||
|
# title = "Уведомление о сookies"
|
||||||
|
# description = """
|
||||||
|
# Мы используем cookie-файлы для улучшения пользовательского опыта и сбора статистики.
|
||||||
|
# Для получения дополнительной информации вы можете ознакомиться с нашей <a href="basics/legal/cookies.html">Политикой использования cookie-файлов</a>.
|
||||||
|
# """
|
||||||
|
# actions = [
|
||||||
|
# "accept",
|
||||||
|
# # "reject,
|
||||||
|
# ]
|
||||||
|
|
||||||
|
# [project.extra.analytics.feedback]
|
||||||
|
# title = "Полезна ли эта страница?"
|
||||||
|
|
||||||
|
# [[project.extra.analytics.feedback.ratings]]
|
||||||
|
# icon = "material/emoticon-happy-outline"
|
||||||
|
# name = "Да, всё понятно"
|
||||||
|
# data = 1
|
||||||
|
# note = "Спасибо за отзыв!"
|
||||||
|
|
||||||
|
# [[project.extra.analytics.feedback.ratings]]
|
||||||
|
# icon = "material/emoticon-sad-outline"
|
||||||
|
# name = "Нет, нужны уточнения"
|
||||||
|
# data = 0
|
||||||
|
# note = "Спасибо за отзыв!"
|
||||||
|
|
||||||
|
[[project.extra.social]] # соц. кнопка в футере
|
||||||
|
name = "Новостной канал в Telegram"
|
||||||
|
icon = "simple/telegram"
|
||||||
|
link = "https://t.me/"
|
||||||
|
|
||||||
|
[[project.extra.social]] # соц. кнопка в футере
|
||||||
|
name = "Сообщество в Telegram"
|
||||||
|
icon = "simple/telegram"
|
||||||
|
link = "https://t.me/"
|
||||||
|
|
||||||
|
[[project.extra.social]] # соц. кнопка в футере
|
||||||
|
name = "YouTube"
|
||||||
|
icon = "simple/youtube"
|
||||||
|
link = "https://www.youtube.com/"
|
||||||
|
|
||||||
|
[[project.extra.social]] # соц. кнопка в футере
|
||||||
|
name = "GitHub"
|
||||||
|
icon = "fontawesome/brands/git"
|
||||||
|
link = "https://git.axenov.dev/anthony/zensical-boilerplate"
|
||||||
|
|
||||||
|
[project.extra.status]
|
||||||
|
beta = "Нестабильный функционал"
|
||||||
|
|
||||||
|
[project.theme] # общие настройки темы
|
||||||
|
custom_dir = "./overrides"
|
||||||
|
language = "ru"
|
||||||
|
logo = "/_assets/logo-mid.png" # относительно docs_dir
|
||||||
|
# favicon = "/_assets/favicon-32x32.png" # относительно docs_dir
|
||||||
|
features = [
|
||||||
|
# "header.autohide", # скрывать заголовок при скролле
|
||||||
|
"content.code.annotate",
|
||||||
|
"content.code.copy",
|
||||||
|
"content.code.select",
|
||||||
|
"content.footnote.tooltips",
|
||||||
|
"content.tabs.link",
|
||||||
|
"content.tooltips",
|
||||||
|
|
||||||
|
# "navigation.instant",
|
||||||
|
# "navigation.instant.prefetch",
|
||||||
|
# "navigation.instant.progress",
|
||||||
|
"navigation.tabs", # 1 уровень навигации превращаются в табы в шапке
|
||||||
|
# "navigation.tabs.sticky", # не скрывать табы под заголовком при скролле
|
||||||
|
"navigation.sections", # заголовки секций меню сворачиваются или статичны
|
||||||
|
"navigation.tracking", # подстановка якорей страницы в урлу при скролле
|
||||||
|
# "navigation.expand", # развёрнутые подменю по умолчанию
|
||||||
|
"navigation.path", # хлебные крошки над H1 страницы
|
||||||
|
"navigation.indexes", # если есть index.md, то пункт меню разворачиваблен и открывает свой index.md
|
||||||
|
"navigation.footer", # прошлый/следующий документ в футере
|
||||||
|
"navigation.top", # кнопка возврата наверх
|
||||||
|
|
||||||
|
"toc.follow", # подсветка загловков содержания при скролле
|
||||||
|
"search.highlight", # подсвечивать поисковый запрос на странице при переходе из поиска
|
||||||
|
|
||||||
|
# "content.action.edit", # редактирование страницы в repo_url
|
||||||
|
# "content.action.view", # исходник страницы в repo_url
|
||||||
|
]
|
||||||
|
|
||||||
|
[project.theme.font]
|
||||||
|
text = "Inter"
|
||||||
|
code = "Jetbrains Mono"
|
||||||
|
|
||||||
|
[[project.theme.palette]] # Светлая тема
|
||||||
|
media = "(prefers-color-scheme: light)"
|
||||||
|
scheme = "default"
|
||||||
|
# primary = "white"
|
||||||
|
accent = "teal"
|
||||||
|
toggle.icon = "lucide/moon"
|
||||||
|
toggle.name = "Включить тёмную тему"
|
||||||
|
|
||||||
|
[[project.theme.palette]] # Тёмная тема
|
||||||
|
media = "(prefers-color-scheme: dark)"
|
||||||
|
scheme = "slate"
|
||||||
|
# primary = "black"
|
||||||
|
accent = "teal"
|
||||||
|
toggle.icon = "lucide/sun"
|
||||||
|
toggle.name = "Включить светлую тему"
|
||||||
|
|
||||||
|
[project.theme.icon]
|
||||||
|
repo = "fontawesome/brands/github"
|
||||||
|
edit = "material/pencil"
|
||||||
|
view = "material/eye"
|
||||||
|
|
||||||
|
[project.theme.icon.tag]
|
||||||
|
default = "lucide/hash"
|
||||||
|
html = "fontawesome/brands/html5"
|
||||||
|
js = "fontawesome/brands/js"
|
||||||
|
css = "fontawesome/brands/css3"
|
||||||
|
vscode = "material/microsoft-visual-studio-code"
|
||||||
|
intellij = "simple/jetbrains"
|
||||||
|
jetbrains = "simple/jetbrains"
|
||||||
|
cli = "material/console"
|
||||||
|
brain = "material/brain"
|
||||||
|
|
||||||
|
[project.extra.tags]
|
||||||
|
HTML5 = "html"
|
||||||
|
JavaScript = "js"
|
||||||
|
CSS = "css"
|
||||||
|
VSCode = "vscode"
|
||||||
|
"VS Code" = "vscode"
|
||||||
|
IntelliJ = "intellij"
|
||||||
|
JetBrains = "jetbrains"
|
||||||
|
CLI = "cli"
|
||||||
|
"модель" = "brain"
|
||||||
|
"модели" = "brain"
|
||||||
|
"ии" = "brain"
|
||||||
|
AI = "brain"
|
||||||
|
LLM = "brain"
|
||||||
|
|
||||||
|
[project.markdown_extensions.pymdownx.highlight]
|
||||||
|
anchor_linenums = true
|
||||||
|
pygments_lang_class = true
|
||||||
|
|
||||||
|
[project.markdown_extensions.pymdownx.emoji]
|
||||||
|
emoji_index = "zensical.extensions.emoji.twemoji"
|
||||||
|
emoji_generator = "zensical.extensions.emoji.to_svg"
|
||||||
|
options.custom_icons = ["./overrides/.icons"]
|
||||||
|
|
||||||
|
[project.markdown_extensions.pymdownx.snippets]
|
||||||
|
base_path = "./snippets"
|
||||||
|
|
||||||
|
[project.markdown_extensions.pymdownx.tabbed]
|
||||||
|
alternate_style = true
|
||||||
|
|
||||||
|
[project.markdown_extensions.toc]
|
||||||
|
permalink = true
|
||||||
|
# title = "На этой странице:"
|
||||||
|
|
||||||
|
[project.markdown_extensions.abbr]
|
||||||
|
[project.markdown_extensions.admonition]
|
||||||
|
[project.markdown_extensions.attr_list]
|
||||||
|
[project.markdown_extensions.def_list]
|
||||||
|
[project.markdown_extensions.footnotes]
|
||||||
|
[project.markdown_extensions.md_in_html]
|
||||||
|
[project.markdown_extensions.inline_badges]
|
||||||
|
[project.markdown_extensions.pymdownx.inlinehilite]
|
||||||
|
[project.markdown_extensions.pymdownx.superfences]
|
||||||
|
# [project.markdown_extensions.pymdownx.keys]
|
||||||
|
[project.markdown_extensions.pymdownx.details]
|
||||||
|
[project.markdown_extensions.pymdownx.caret]
|
||||||
|
[project.markdown_extensions.pymdownx.mark]
|
||||||
|
[project.markdown_extensions.pymdownx.tilde]
|
||||||
Reference in New Issue
Block a user