Всё записано

Документация

Q: Где документация к моей версии?

Внутри образа, который вы запускаете. heron docs печатает её, поэтому ответ всегда совпадает с вашим HERON, даже без интернета. На этом сайте лежит полная копия последней стабильной версии, и каждая страница ссылается на свой источник в ветке prod. Подробнее — документация в терминале .

Q: С чего начать чтение?

С восьми идей на этой странице, потом понятия и первый сайт . Дальше открывайте страницу, только когда она понадобится; как работать с каждым документом подскажет, какую.

Q: Можно дать документацию ИИ-агенту?

Да. heron docs --export .heron-docs выгружает всю документацию папкой. Агент читает правила ровно вашей версии и не угадывает. Подробнее — в разделе HERON для ИИ .

Q: Что будет, когда я обновлю HERON?

Сайты продолжат собираться версией из своего site.yaml . Чтобы перевести сайт на новую, поменяйте эту строку, запустите строгую сборку и поправьте то, что она покажет.

Всё, что делает HERON, записано: на этом сайте, в репозитории и внутри образа, и всегда совпадает с версией, которую вы запускаете. Вся документация репозитория перенесена сюда целиком, на русском и английском: гайды, спецификации и роли для ИИ-агентов.

Эти правила читают и люди, и ИИ-агенты, поэтому сайт, собранный руками, и сайт, собранный агентом, живут по одному контракту. Начните с восьми идей ниже, а потом прочитайте гайды по порядку.

ОсновыНикогда не делали сайт? Начните здесь: Docker, редактор, Markdown, git и GitHub, как работает сборка, домен и что делать, если что-то не так.Как читать документациюВсе документы HERON: на что отвечает каждый, кто и когда его читает. Каждый перенесён на этот сайт целиком, со ссылкой на последнюю версию в git.ПонятияСемь понятий, на которых стоит HERON: папка сайта, контракт, ключ и адрес страницы, языки, SEO-блок, секции и формы, тема и сборка.Первый сайтОт пустой папки до собранного сайта на двух языках: создать, описать в site.yaml, написать главную, добавить страницу, посмотреть и собрать для прода.Страницы и контентКак устроена страница HERON и как добавлять разделы, ссылки, связи, картинки и переводы. Для того, кто ведёт сайт, — человека или ИИ-агента.Тема и дизайнКак устроена тема HERON и как сделать свою: theme.yaml, шаблон на каждый тип страницы, модули, что видит шаблон, строки интерфейса и картинки.SEO и языкиЧто HERON сам пишет для поисковиков и нейросетей, что заполняете вы, как устроены языки и как переехать со старого сайта без потери позиций.Сборка и выкладкаСобрать сайт для прода, упаковать в образ nginx, подключить свой nginx, проверить все коды ответа и вести несколько сайтов на разных версиях HERON.Формы секцийВсе формы секций HERON: как писать, живой результат, HTML и CSS. Текст, список, шаги, карточки, две колонки, таблица, вопросы, факты, врезка.СпецификацииОткрытый контракт между HERON и папкой сайта, сборка, развёртывание и поставка целиком. Каждая страница ссылается на свою последнюю версию в git.Роли для ИИ-агентовЕдиная инструкция для ИИ-агента, который работает над сайтом на HERON: четыре роли, что на входе и выходе, общие правила и карта документации.Документация в терминалеЧитайте, ищите и выгружайте документацию ровно той версии, что запущена, без интернета. И команды, которые создают, проверяют, показывают и собирают сайт.СловарьПростые объяснения: markdown, фронтматтер, слаг, образ, реестр, статический сайт, sitemap, canonical, hreflang, schema.org, llms.txt, 301 и другие.План развитияЧто запланировано в HERON: подключение данных по желанию, формы, навыки для ИИ-агентов, расширенный конфигуратор, сравнения и настройки поисковиков.

Никогда этим не занимались? Начните здесь

Если вы ни разу не делали сайт, начните с Основ. Там показано, как поставить Docker на macOS, Windows или Linux, какой текстовый редактор взять, как устроен Markdown на настоящей странице, как завести аккаунт GitHub и что происходит, когда HERON собирает ваш сайт. Полчаса там — и всё остальное здесь читается легко.

Восемь идей для начала

Эти восемь идей — весь HERON в миниатюре. Откройте карточку, чтобы увидеть подробности и пример; целиком каждая идея разобрана на странице понятия.

Сайт — это папка

Ваш сайт — обычная папка на компьютере: страницы, фото, данные и один файл настроек. Программного кода в ней нет, поэтому её можно открыть, скопировать, сохранить в архив и отправить, как любую другую папку.

Что внутри: content/ — страницы, media/ — фото и документы, data/ — списки вроде цен или команды, static/ — файлы, которые выходят в интернет как есть, theme/ — внешний вид, site.yaml — настройки.
Почему это важно: В папке нечему сломаться или взломаться: это текст и картинки. Сервер показывает только готовые страницы.
Что делаете вы: Один раз создаёте её командой heron new my-site -y, настраиваете в конфигураторе, дальше правите файлы в любом текстовом редакторе.
Храните в git: Раз это обычный текст, git помнит каждую правку, и можно вернуться в любой день.

heron new my-site -y && cd my-site && ls

Что лежит в папке сайта →

HERON — отдельная программа

HERON — инструмент, который читает вашу папку и превращает её в сайт. Он живёт отдельно от сайта, в образе Docker или пакете pip, поэтому папка остаётся чистой, а один HERON обслуживает сколько угодно сайтов.

Как запускать: Одной командой Docker или короткой командой heron, которую один раз настраивают на странице С чего начать.
В сайт ничего не ставится: Ни плагинов, ни скопированных программных файлов. Обновили HERON — выиграли все сайты, когда вы сами решите.
Какая версия: Первая строка site.yaml говорит, какие версии подходят, например heron: ">=0.1,<0.2". Чужая версия откажется собирать, а не сломает сайт.
Документация едет вместе с ним: heron docs печатает документацию ровно той версии, что вы запускаете, даже без интернета.

Документация в терминале →

Страница — текстовый файл

Каждая страница сайта — один текстовый файл. Имя файла становится адресом: about.md в папке вашего языка превращается в страницу /about/. Пишете в любом редакторе, особая программа не нужна.

Верх файла: Блок между двумя строками --- хранит настройки страницы: title для выдачи поисковика, description для описания под ним, h1 для заголовка на самой странице.
Всё остальное: Обычный текст в Markdown: заголовки, абзацы, списки, ссылки, картинки.
Новая страница: Скопируйте похожий файл, сохраните под новым именем, поменяйте текст. Следующая сборка сделает из него страницу.
Адрес: В имени файла латиница, цифры и дефис: roof-repair.md даст адрес /roof-repair/.

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

Секция — блок на странице

Страница разрезана на секции. Каждая начинается с заголовка и якоря: ## Цены {#prices}. Заголовок читают посетители, якорь подсказывает теме, какой блок там нарисовать.

Пример: ## Вопросы {#faq} и под ним вопросы через ### становятся раскрывающимся списком вопросов и ответов.
Форма угадывается: Нумерованный список станет шагами, таблица — таблицей, три группы ### со списками — карточками. Вы просто пишете.
Порядок свободный: Тема сама ставит секции на места, поэтому перестановка текста никогда не ломает вёрстку.
Все формы наглядно: Справочник форм показывает markdown, результат, HTML и стили рядом.

Формы секций →

Каждый язык — своя папка

Второй язык — вторая папка с теми же файлами, например content/en/about.md и content/de/about.md. Одинаковое имя файла значит «это переводы друг друга».

Адреса: У основного языка префикса нет (/about/), у остальных есть (/ru/about/). Свой адрес у перевода задаётся через slug:.
Для поисковиков: HERON пишет ссылки hreflang, и Google показывает нужный язык в каждой стране.
Для посетителей: Переключатель языка на каждой странице ведёт на ту же страницу на другом языке.
Добавить язык: Допишите его в languages в site.yaml и запустите heron init .: появится новая папка с главной и страницей 404.

Многоязычный сайт →

Тема — это внешний вид

Тема — то, как выглядит сайт: шаблоны, стили, шрифты, значки в theme/. Ваших текстов в ней нет, поэтому дизайн можно сменить, не трогая ни одной страницы.

Разделение: Тексты живут в content/, вид — в theme/. Дизайнер и автор текстов не мешают друг другу.
Готовые темы: Возьмите тему с демо-страницами, замените тексты и фото, и сайт ваш.
Своя тема: Шаблон на каждый тип страницы и модуль на каждую форму секции. Гайд по теме объясняет каждое правило.
ИИ-агенты: Агент по контенту тему не трогает; агент-дизайнер работает только в theme/.

Темы →

site.yaml — настройки

Один файл хранит всё про сайт целиком: название, домен, языки, меню, реквизиты, аналитику. Все страницы и разметка для поиска берут факты отсюда, поэтому телефон живёт в одном месте.

Пример: site: с domain: example.com и languages: [en, ru], organization: с названием компании.
Конфигуратор: heron setup . — анкета: название, домен, контакты и реквизиты, вид организации для поисковой разметки, тема. Он пишет этот файл за вас, с подсказкой у каждого вопроса.
Строка версии: Первая строка закрепляет версию HERON, нужную сайту.
Каждый ключ: Справочник site.yaml перечисляет все блоки и что они меняют.

Конфигуратор →

Сборка проверяет всё

heron build превращает папку в готовый сайт в dist/ и по дороге проверяет его. Битая ссылка, пропущенный перевод или пустое описание попадают в отчёт с файлом, строкой и подсказкой, что делать.

Обычная сборка: Показывает предупреждения и всё равно собирает, чтобы можно было посмотреть черновик.
Строгая сборка: heron build . --env prod --strict превращает каждое предупреждение в ошибку. Именно она уходит в интернет.
Как читать ошибку: В ней код (например, E005), файл и строка, и подсказка. Частые ошибки разобраны в разделе если что-то не так.
Быстро: Стартовый сайт собирается меньше чем за секунду, тысяча страниц на двух языках — примерно за 3 секунды.

heron build . --env prod --strict && ls dist

Как работает сборка →

Читать по порядку

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

1
Понятия

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

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

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

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

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

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

Когда нужен точный ответ

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

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

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

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

Справочник форм

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

Когда читать: Пишете страницу и выбираете подходящую форму для блока.
Что видно: Исходный текст, живой результат, HTML и CSS за ним, плюс цветовые варианты для сравнения.
Девять форм: Текст, список, шаги, карточки, две колонки, таблица, вопросы, факты, врезка.
Совет: Скопируйте markdown из справочника в свою страницу и поменяйте слова.

Справочник форм →

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

Архитектор, контент и SEO, дизайнер, сборщик: что каждая роль читает, что выдаёт и чего не трогает, плюс что HERON уже умеет. Дайте одну из этих страниц агенту — и он будет работать по правилам, а не угадывать.

Когда читать: Передаёте работу ИИ-агенту или ставите задачу человеку.
Архитектор: Планирует структуру: страницы, типы, языки, старые адреса.
Контент и SEO: Пишет и заполняет страницы; тему не трогает.
Дизайнер: Делает тему; тексты не трогает.
Сборщик: Собирает, проверяет и публикует, а в отчёте пишет, что осталось.

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

Версии HERON

HERON публикуется образами с тегами. Тег — это имя версии.

Тег	Что это	Кому
prod	Стабильная версия: проверена и рекомендована	Живым сайтам и всем, кто начинает
beta	Следующая версия, её обкатывают на живых сайтах, прежде чем сделать стабильной	Тем, кто хочет новые возможности раньше
dev	Рабочая версия с последними изменениями	Тем, кто разрабатывает сам HERON
0.1.0	Точный выпуск, который не меняется никогда	Сайтам, которые годами должны собираться одинаково
latest	Самый новый точный выпуск	Быстрым экспериментам

Вопросы

Где документация к моей версии?

Внутри образа, который вы запускаете. heron docs печатает её, поэтому ответ всегда совпадает с вашим HERON, даже без интернета. На этом сайте лежит полная копия последней стабильной версии, и каждая страница ссылается на свой источник в ветке prod. Подробнее — документация в терминале.

С чего начать чтение?

С восьми идей на этой странице, потом понятия и первый сайт. Дальше открывайте страницу, только когда она понадобится; как работать с каждым документом подскажет, какую.

Можно дать документацию ИИ-агенту?

Да. heron docs --export .heron-docs выгружает всю документацию папкой. Агент читает правила ровно вашей версии и не угадывает. Подробнее — в разделе HERON для ИИ.

Что будет, когда я обновлю HERON?

Сайты продолжат собираться версией из своего site.yaml. Чтобы перевести сайт на новую, поменяйте эту строку, запустите строгую сборку и поправьте то, что она покажет.