130 lines
7.9 KiB
Markdown
130 lines
7.9 KiB
Markdown
# 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
|