Перевод на zensical и актуализация

2026-07-11 15:09:32 +08:00
parent 7ec67ef918
commit 82a98edf00
18 changed files with 1771 additions and 874 deletions
@@ -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