zensical-boilerplate/AGENTS.md

KODA.md — контекст проекта

Обзор проекта

Бойлерплейт для документации на базе Zensical — системы документации, построенной на 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.

Лицензия

MIT License