Понятия

Представьте HERON типографией, а свой сайт — рукописью. Вы пишете рукопись (текстовые файлы в папке), типография (HERON) превращает её в готовую книгу (сайт), а оформление книги (тема) выбирается отдельно от текста. Обложку и шрифты можно сменить, не переписывая ни одной главы.

Пример. Вы создаёте файл content/ru/prices.md, пишете в нём заголовок и таблицу цен и запускаете сборку. HERON читает файл, видит адрес страницы, рисует таблицу блоком таблицы из темы и добавляет страницу в меню, карту сайта и llms.txt. Код вы не трогали.

Прочитайте эту страницу первой, до остальных гайдов: все следующие страницы пользуются словами, которые здесь объяснены (папка, страница, ключ, адрес, секция, тема, сборка). Совсем новичок? Начните ещё раньше — с Основ.

HERON — это программа heron. Она приходит образом ghcr.io/fmstm/heron:TAG или pip-пакетом. Её не копируют в сайт и не правят под сайт.

Сайт — папка, в которой нет ни строчки кода HERON:

мой-сайт/
├── site.yaml       настройки: домен, языки, тема, меню, SEO
├── content/        страницы в markdown, по папке на язык
├── media/          картинки, видео, документы
├── data/           yaml-справочники: отзывы, команда, реквизиты
├── static/         файлы по точному адресу: favicon, .well-known
├── theme/          тема: шаблоны Jinja2, стили, строки интерфейса
└── plugins/        свои плагины, обычно пусто

Сайт объявляет, какой HERON ему нужен, первой строкой site.yaml: heron: ">=0.1,<0.2". Один HERON обслуживает любое число сайтов, и у каждого сайта может быть своя версия.

Подробно: папка сайта в спецификации.

Контракт — договор между HERON и папкой сайта: какие файлы где лежат, какие поля у страницы, какие ключи у site.yaml, что HERON сделает сам и на что ответит ошибкой. Он один для всех сайтов и записан в спецификации. Нарушение контракта — внятная ошибка с кодом, файлом и строкой (E002, E006…), а не молча сломанная страница.

Страница — это markdown-файл. Путь файла задаёт адрес. Пример для default_lang: en, languages: [en, ru]:

content/en/index.md                →  /
content/en/about.md                →  /about/
content/en/services/_index.md      →  /services/              страница самого раздела
content/en/services/design.md      →  /services/design/
content/ru/about.md                →  /ru/o-nas/              slug: o-nas
content/ru/services/_index.md      →  /ru/uslugi/             slug: uslugi
content/ru/services/design.md      →  /ru/uslugi/dizajn/      slug: dizajn

У страницы две разные вещи, которые по умолчанию совпадают:

• ключ — путь файла без .md: services/design. Он одинаков во всех языках. По нему HERON связывает переводы, по нему страницу называют в меню и в ссылках;
• адрес — то, что видит посетитель. Его меняет поле slug, а ключ остаётся прежним. Поэтому у русской версии адрес /ru/uslugi/dizajn/, а ключ тот же — services/design.

Главная — index.md, её ключ /. Страница «не найдено» — 404.md.

Подробно: дерево контента и адреса.

Язык — папка в content/. Список языков и язык по умолчанию задаёт site.yaml:

site:
  default_lang: en       # отдаётся из корня: /about/
  languages: [en, ru]    # остальные — с префиксом: /ru/o-nas/

Перевод — файл с тем же именем в папке другого языка, адрес у него может быть свой (slug). Переведённые страницы получают hreflang друг на друга, x-default — версия языка по умолчанию. Поменять default_lang — значит поменять адреса всех страниц.

Подробно: языки в спецификации.

Каждый файл страницы начинается с SEO-блока — YAML между двумя строками ---, разбитого на восемь групп с комментариями: основное, ключевые запросы, Open Graph, Twitter, schema.org, карточка, служебное, связи. Обязательны три поля: title, h1, description. Остальное — по мере надобности, пустые поля остаются закомментированными.

Стартовые страницы приходят с полным блоком, а heron page кладёт его в каждую новую. Новая страница — копия файла с правкой значений.

Подробно: формат страницы.

После SEO-блока идёт текст. Текст до первого заголовка — вступление. Дальше — секции:

## Как мы работаем {#how}

1. **Заявка.** Пишете или звоните.
2. **Встреча.** Обсуждаем задачу.

{#how} — якорь, адрес секции для темы. Порядок секций в файле не важен: тема ставит каждую на своё место по якорю. Форму секции HERON понимает по разметке: нумерованный список — шаги, ### Вопрос? — FAQ, строки ключ | значение — факты, таблица — таблица. Всего форм двенадцать.

Подробно: секции и формы, а справочник форм показывает каждую так, как её рисует тема.

Тема — папка theme/: шаблоны Jinja2, модули, стили, строки интерфейса. Она решает, как выглядит сайт; контент решает, что на нём написано.

Тип страницы выбирает шаблон: страница типа service рисуется theme/templates/service.html. Тип задаётся полем type в файле или children_type в _index.md раздела. У главной тип home, по умолчанию — page. В theme/theme.yaml тема описывает свои типы, их секции, связи между страницами и пропорции картинок.

Подробно: theme.yaml в спецификации и гайд по теме.

heron build читает папку, проверяет её по контракту и собирает dist/: HTML страниц, sitemap.xml, robots.txt, llms.txt, разметку JSON-LD, нарезанные картинки, карты 301 и 410 и конфиг nginx. Рабочая сборка (по умолчанию) закрыта от поисковиков; боевая — --env prod. Результат — либо папка на любой хостинг, либо образ nginx с сайтом внутри.

Подробно: этапы сборки и гайд по сборке и выкладке.

Эта страница повторяет docs/guide/01-concepts.md из ветки prod. Репозиторий обновляется первым, поэтому там всегда самая свежая версия.

Следующий гайд: Первый сайт.