Карта документации

Как работать с каждым документом

У HERON около двадцати документов, и каждый отвечает на свой вопрос. Эта страница подскажет, какой открыть, для кого он написан и когда его читать.

Каждый документ целиком перенесён на этот сайт, читать можно здесь. Те же файлы лежат в репозитории, где обновляются первыми (ветка prod всегда показывает последнюю стабильную версию), и внутри образа: heron docs с названием темы печатает нужный.

Простыми словами

У HERON много документов — как в поваренной книге, где у каждого вида блюд своя глава. Поваренную книгу не читают от корки до корки: открывают нужную главу. Эта страница — оглавление, которое подсказывает, какая глава отвечает на ваш вопрос.

Пример. Сборка остановилась с «E007». Не нужно перечитывать гайды с начала: таблица ниже говорит «Что значит этот код ошибки? → Сборка, коды ошибок», вы открываете ту страницу и находите строку про E007.

Эта страница нужна, когда непонятно, где искать. Её можно пропустить, если вы идёте по гайдам подряд: каждый ссылается на следующий.

Какой документ на что отвечает

Ваш вопрос	На этом сайте	В терминале
Что такое HERON, с чего начать?	[С чего начать](/get-started/)	heron docs readme
Я ИИ-агент, откуда начинать?	[Роли для агентов](/docs/agents/)	heron docs agents
Какие основные идеи?	[Понятия](/docs/concepts/)	heron docs concepts
Как сделать первый сайт?	[Первый сайт](/docs/first-site/)	heron docs first-site
Как писать страницы и секции?	[Страницы и контент](/docs/content/)	heron docs pages
Какая форма подходит моему блоку?	[Справочник форм](/docs/forms/)	heron docs contract
Как сделать тему?	[Тема и дизайн](/docs/theme/)	heron docs theme
Поисковики и переезд?	[SEO и языки](/docs/seo/)	heron docs seo
Как опубликовать?	[Сборка и выкладка](/docs/deploy/)	heron docs deploy
Что именно можно писать в файле?	[Спецификации](/docs/spec/)	heron docs contract
Что значит код ошибки?	[Сборка, коды ошибок](/docs/spec/engine/#errors)	heron docs --search "E015"
Умеет ли HERON уже вот это?	[Что умеет HERON](/docs/agents/capabilities/)	heron docs capabilities

С чего начать

README

Первое знакомство с HERON: что это, быстрый старт одной командой, как один HERON обслуживает несколько сайтов. На этом сайте то же рассказывают главная и «С чего начать».

Кому: Всем, в первый день.
Когда: Раньше всего остального и когда объясняете HERON кому-то ещё.
Что вы поймёте: Сайт — это папка текстовых файлов, HERON — отдельная программа, которая его собирает, а всё начинается с одной команды.
Сколько времени: Пять минут. Это самый короткий документ.
Попробуйте: heron docs readme покажет тот же текст в терминале, без интернета.

С чего начать · README в git

AGENTS.md

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

Кому: Claude Code, Codex и любому другому агенту, а также тем, кто ставит им задачи.
Когда: Агент читает его первым, до любого другого файла.
Что внутри: Четыре роли (архитектор, контент и SEO, дизайнер, сборщик), что каждая читает и выдаёт, общие правила и карта всех документов.
Как пользоваться: Дайте агенту ссылку на репозиторий или выполните heron docs --export .heron-docs и укажите ему эту папку.
Чем помогает: Агент перестаёт угадывать: он знает, какие папки можно трогать и какая проверка доказывает, что работа сделана.

Роли для агентов · AGENTS.md в git

CHANGELOG

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

Кому: Тем, кто обновляет HERON или диапазон версий сайта.
Когда: Перед тем как поменять строку heron: в site.yaml.
Что внутри: Каждая версия и её изменения по разделам: сборка, контракт, команды, документация.
Как читать: Найдите версию, на которую переходите, и прочитайте раздел «Контракт»: именно он может потребовать правок в ваших файлах.
После чтения: Поменяйте строку версии, запустите heron build . --env prod --strict и поправьте то, что покажет отчёт.

CHANGELOG в git

Гайды по порядку

Каждый гайд опирается на предыдущий. Прочитайте их один раз подряд, а потом возвращайтесь к нужному.

1
Понятия

Папка, страница, ключ, адрес, секция, языки, тема, настройки, сборка: идеи, на которых стоит всё остальное.
Понятия
2
Первый сайт

От пустой папки до собранного сайта на двух языках.
Первый сайт
3
Страницы и контент

Блок настроек для поиска вверху страницы, секции и их формы, ссылки, картинки, переводы.
Страницы и контент
4
Тема и дизайн

theme.yaml, шаблоны, модули, строки интерфейса, картинки в теме.
Тема и дизайн
5
SEO и языки

Что пишется для поисковиков само, что заполняете вы, языки, переезд со старого сайта.
SEO и языки
6
Сборка и выкладка

Два результата — папка или образ, окружения сайта, несколько сайтов, проверки перед запуском.
Сборка и выкладка

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

Точные правила. Открывайте раздел, когда гайда мало или когда двое спорят, как что-то работает. Все спецификации →

20 · Контракт

Договор между HERON и папкой сайта. На этом сайте он разделён на пять страниц: папка сайта и адреса, формат страницы, site.yaml, theme.yaml, картинки и файлы.

Кому: Редакторам, дизайнерам, агентам.
Когда: Нужно точное имя или смысл поля.
Пример вопроса: «Может ли у русской страницы быть свой адрес?» Страница о папке сайта отвечает: да, через slug:, и показывает результат.
Что решает: Споры. Если страница и контракт расходятся, прав контракт, а страницу правят.
Объём: Большой, поэтому ищите нужное поле, а не читайте подряд.

Спецификация 20 в git

21 · Сборка

Этапы сборки, что видит шаблон, все команды и все коды ошибок с тем, как их исправить.

Кому: Разработчикам тем и тому, кто чинит упавшую сборку.
Когда: Сборка остановилась с кодом или шаблону нужно значение.
Коды ошибок: У каждого кода (E002, E005, E015…) есть строка: что случилось и что делать. Начинайте с неё, когда сборка остановилась.
Команды: Все команды и флаги heron с примерами.
Авторам тем: Полный список того, что получает шаблон: страница, сайт, секции, помощники.

Сборка · Спецификация 21 в git

22 · Развёртывание

Контейнеры, скрипты обновления, CI, nginx, переезд старого сайта с переадресациями, бэкап.

Кому: Тому, кто отвечает за сервер или репозиторий на GitHub.
Когда: Перед первой публикацией и перед переездом.
Что внутри: Как сайт работает в контейнере, как приходят обновления, как CI собирает образ, как настроен nginx и как старый сайт переезжает, не теряя адресов.
Пример: Переезд с WordPress: таблица старых адресов превращается в настоящие переадресации 301 в конфиге nginx.
Не нужно, если: Вы публикуете статику на GitHub Pages; тогда хватит гайда сборка и выкладка.

Развёртывание · Спецификация 22 в git

23 · Поставка

Как приходит HERON: образ, пакет pip, теги, образ сайта и его проверки, формы, безопасность сборки.

Кому: Тому, кто выбирает версию или собирает образы.
Когда: Закрепляете версию или настраиваете сервер.
Что внутри: Теги образа (prod, beta, dev, точные версии), пакет pip, образ сайта с nginx, дымовая проверка, что он открывается, и правила безопасности сборки.
Пример: Закрепите ghcr.io/fmstm/heron:0.1.0 у сайта, который годами должен собираться одинаково.
Читать вместе с: Таблицей версий на главной странице документации.

Поставка · Спецификация 23 в git

Роли для ИИ-агентов

Работа над сайтом делится на четыре роли. Один агент может пройти их все, а может получить одну и передать результат дальше. Все роли →

Архитектор

Проектирует структуру нового сайта по старому или по брифу: страницы, ключи, типы, языки, таблицу старых адресов.

Результат: Документ структуры, черновик site.yaml, вопросы владельцу.
На входе: Старый сайт, его карта сайта или короткое описание задачи от владельца.
Делает: Перечисляет все страницы, решает их ключ, тип и язык и для каждого старого адреса выбирает: переадресация (301) или «больше нет» (410).
Не делает: Тексты и тему: их передаёт дальше.

Архитектор

Контент и SEO

Пишет страницы, заполняет блок для поиска, добавляет переводы и старые адреса.

Результат: Файлы в content/, картинки в media/, список недостающих фактов.
На входе: Структура от архитектора или готовый сайт, плюс факты от владельца.
Делает: Копирует файл страницы под новым именем, заполняет title, h1, description, пишет секции, добавляет переводы.
Не делает: Не трогает theme/, скрипты и структуру site.yaml; не выдумывает телефоны и цены.

Контент и SEO

Дизайнер

Делает тему: шаблон на каждый тип страницы, модуль на каждую форму блока.

Результат: Папка theme/, которая рисует каждую страницу, даже с неполным контентом.
На входе: Типы страниц и их секции, плюс макет или описание внешнего вида.
Делает: Пишет шаблоны, по модулю на каждую форму секции, строки интерфейса на всех языках, стили.
Не делает: Не кладёт в тему тексты сайта: тексты живут в страницах, факты — в site.yaml.

Дизайнер

Сборщик

Сводит всё вместе, запускает строгую сборку, делает образ и отчёт.

Результат: Сайт, который собирается с --env prod --strict и отвечает правильными кодами.
На входе: Всё, что сделали другие роли, или просто «собери по структуре».
Делает: Гоняет строгую сборку, пока она не станет чистой, делает образ, запускает дымовую проверку, публикует.
Отчитывается: Что сделано, какого контента ещё нет, какие предупреждения оставлены осознанно.

Сборщик

Что HERON уже умеет

Список по задачам. Прочитайте его, прежде чем просить новую возможность: почти всё, что нужно сайту, уже есть.

Кому: Архитекторам, агентам, всем, кто планирует сайт.
Пример: «Может ли страница быть в двух разделах?» Да, через связи между страницами, без копирования.
Почему читать первым: Большинство просьб о «новой функции» уже закрыты; это экономит дни.
Честный список: В нём же сказано, чего HERON не делает намеренно, и почему.

Что умеет HERON

Образцы файлов

Образцы страницы, site.yaml, theme.yaml и плана структуры, каждое поле с пояснением. Их проверяют тесты, поэтому они не устаревают.

Кому: Всем, кто создаёт файл с нуля.
Что там: Страница со всеми восемью группами блока для поиска, полный site.yaml, theme.yaml и план структуры.
Как пользоваться: Скопируйте образец, оставьте комментарии, впишите значения. Комментарии объясняют каждое поле.
Не устаревают: Тесты HERON собирают эти образцы, поэтому они всегда совпадают с текущей версией.

Образцы в git

Записки в папке сайта

heron new кладёт короткую записку heron-readme.md в папку сайта и в каждую папку внутри: content, media, data, static, theme. Каждая говорит, что в этой папке лежит, а чего в ней быть не должно.

Прочитайте их, когда впервые открываете папку. HERON никогда не превращает их в страницы, поэтому они могут оставаться в репозитории. Язык записок выбирается при создании: heron new --notes ru.

Вопросы

Нужно ли читать всё?

Нет. Прочитайте восемь идей на странице документации и первый сайт, а дальше открывайте документ, только когда появляется вопрос. Таблица вверху страницы подскажет, какой.

Этот сайт, git и мой образ расходятся. Что верно?

Для вашего сайта — то, что в образе: оно совпадает с HERON, который собирает ваш сайт. Git в ветке prod показывает последнюю стабильную версию и обновляется первым, этот сайт — сразу следом.

В документации написано одно, а HERON делает другое. Что делать?

Это ошибка HERON, а не вашего сайта. Запишите файл, команду и что произошло и сообщите в репозитории.

На каком языке документы?

Документы в репозитории написаны по-русски. На этом сайте полный текст есть на русском и английском, так что читать можно и вам, и вашему ИИ-агенту.

Как работать с каждым документом

Простыми словами

Какой документ на что отвечает

С чего начать

README

AGENTS.md

CHANGELOG

Гайды по порядку

Понятия

Первый сайт

Страницы и контент

Тема и дизайн

SEO и языки

Сборка и выкладка

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

20 · Контракт

21 · Сборка

22 · Развёртывание

23 · Поставка

Роли для ИИ-агентов

Архитектор

Контент и SEO

Дизайнер

Сборщик

Что HERON уже умеет

Образцы файлов

Записки в папке сайта

Вопросы

Нужно ли читать всё?

Этот сайт, git и мой образ расходятся. Что верно?

В документации написано одно, а HERON делает другое. Что делать?

На каком языке документы?