# 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