Спецификации

Представьте HERON как повара, который готовит строго по книге рецептов. Спецификации — эта книга: какие продукты кладут в папку сайта (страницы, фотографии, один файл настроек) и что получается на выходе (готовые страницы, карта сайта, файлы для поисковиков и нейросетей). «Само как-то» здесь ничего не происходит: каждое правило записано.

Раз правила записаны, на одном сайте могут работать совсем разные помощники и не мешать друг другу: вы правите текст, дизайнер меняет внешний вид, ИИ-агент добавляет страницы. Все трое читают один и тот же текст.

Пример. Правило из контракта: файл content/ru/about.md становится страницей /ru/about/. Это нигде не настраивается. Вы создаёте файл, и после следующей сборки страница на месте.

content/en/about.md   →   https://example.com/about/
content/ru/about.md   →   https://example.com/ru/about/

Когда эти страницы нужны. Когда сборка остановилась с кодом ошибки, когда нужно точно знать, что делает поле, или когда вы передаёте сайт агенту и хотите, чтобы он соблюдал правила.

Когда можно пропустить. Чтобы сделать и опубликовать первый сайт, хватит гайдов. Возвращайтесь сюда, когда нужен точный ответ.

Контракт — договорённость двух сторон. Здесь одна сторона — HERON, другая — папка вашего сайта. Сайт обещает держать файлы в оговорённых местах и форматах, а HERON — собирать его каждый раз одинаково и точно говорить, что не так, если что-то не подходит.

Договорённость записана и открыта, поэтому читать код HERON не нужно никому — ни человеку, ни ИИ-агенту. Если документация и поведение расходятся, это ошибка HERON, и её исправляют в HERON вместе с текстом.

Контракт — это ещё и обещание во времени. Сайт, который следует ему сегодня, соберётся и завтра: стабильная версия HERON собирает и старые сайты, а возможности добавляются и убираются только обдуманно, со сменой версии.

Как каждая форма секции выглядит на настоящей странице, с её markdown, HTML и стилями, — справочник форм.

• Один источник. Спецификации лежат в репозитории HERON, рядом с кодом, который описывают.
• Одна правка — один коммит. Меняется поведение — его описание меняется в том же коммите. Тесты проверяют образцы файлов, поэтому устаревший образец упадёт раньше, чем его кто-то скопирует.
• Сначала git, следом этот сайт. Изменение сначала попадает в репозиторий, копия на сайте обновляется сразу за ним, поэтому разрыв между ними минимальный. Каждая страница здесь заканчивается разделом «Источник» с именем файла и ссылкой на него.
• Постоянные ссылки. Ссылки на ветку prod всегда показывают последние стабильные правила, например 20-data-contract.md в ветке prod. Точная версия, например 0.1.0, хранит свою копию навсегда.
• Внутри образа. heron docs contract печатает версию, которая совпадает с вашим HERON, даже без интернета. Подробнее — документация в терминале.

HERON — файловый сборщик сайтов. На вход папка с контентом, картинками, темой и одним конфигом. На выходе статический сайт в dist/ или готовый образ nginx с этим сайтом внутри.

HERON не копируется в сайт. Он поставляется одним артефактом — образом heron:<версия> (и тем же кодом как pip-пакет для локальной разработки). Сайт объявляет нужную версию в site.yaml, и HERON отказывается собирать сайт, версию которого не поддерживает.

HERON делается сразу под несколько разных сайтов: спроектированный по одному, он вырождается в этот сайт с абстрактными именами переменных.

Стек

Ядро: Python 3.12 · Jinja2 · markdown-it-py · pydantic · Pillow · click. Пакетный менеджер uv, линтер ruff, тесты pytest.

Обвязка: Docker · nginx · Bash.

Сервис форм (heron-relay, отдельный компонент, позже): FastAPI, без базы; SQLite подключается только как спул повторной отправки.

Компоненты

• heron/core/ — парсер markdown, дерево и URL, резолв связей, рендерер, обработка картинок;
• heron/modules/ — генераторы: sitemap, robots, llms.txt, JSON-LD, hreflang, redirects, feed;
• heron/contracts/ — pydantic-схемы site.yaml, theme.yaml, фронтматтера, версии HERON;
• heron/cli.py — команды new, init, check, serve, build, page;
• scripts/site.sh — сборка, упаковка в образ nginx, просмотр и проверка сайтов из репозитория HERON; настройки в env/.env.<сайт>.<окружение>;
• папка сайта — site.yaml, content/, data/, media/, static/, theme/, plugins/. Кода HERON, Dockerfile, compose и скриптов сборки в ней нет;
• heron-relay — отдельный сервис приёма форм: почта, вебхук в CRM, Telegram. Разворачивается только там, где формы есть.

Решения

Зафиксированы в спецификации поставки:

• сборщик статики вместо Django/Wagtail — сайту нечего обслуживать в рантайме;
• ядро поставляется образом и версией, а не копией в каждом репозитории сайта: три копии ядра означают три расходящихся сборщика;
• формы обслуживает отдельный сервис, а не HERON: HERON обязан остаться «один проход, без состояния, вышел»;
• база данных не хранит ни контент, ни настройки сайта. Источник истины — файлы. Нарушение этого правила превращает HERON в WordPress;
• макеты дизайна переводятся в Jinja2, support.js (69 КБ React-рантайма) в прод не идёт;
• сборка идёт без сети: --network=none, ничего не докачивается на этапе сборки.

Схема

                папка сайта
   site.yaml · content/ · data/ · media/ · static/ · theme/
                     |
                     v
        heron:<версия>   (образ или pip-пакет)
     контракты -> парсер -> резолв -> рендер -> генераторы
                     |
          +----------+-----------+
          v                      v
        dist/               образ nginx
      (на хостинг)     (site.sh image на хосте)
          |
          v
        nginx  ------>  посетитель
                            |
                            v
                     heron-relay (позже)
                       |    |     |
                     почта  CRM  Telegram

Сайт не зависит от heron-relay: сервис лежит — статика продолжает отдаваться, теряется только отправка формы.

Текст архитектуры повторяет docs/architecture.md в ветке prod (правка 2026-10-04).