Формат страницы

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

Секция начинается со строки вида ## Наши цены {#prices}. Слова — заголовок, который видят люди. Часть в фигурных скобках — короткая метка (якорь), по которой тема понимает, куда поставить блок. Заголовок можно переименовывать сколько угодно, метка остаётся.

Пример. Небольшая, но полная страница:

---
title: "Ремонт крыши в Вене: цены и сроки"
h1: "Ремонт крыши"
description: "Ремонт крыши в Вене: что чиним, сколько длится, сколько стоит."
nav_title: "Крыши"
---

Ремонтируем плоские и скатные крыши в Вене и окрестностях.

## Что чиним {#what}

- Протечки после бурь.
- Старые покрытия и водостоки.

## Вопросы {#faq}

### Сколько длится ремонт?
От одного до трёх дней для большинства крыш.

HERON смотрит, как написана секция, и сам определяет её форму: список выше станет списком, вопросы ### — раскрывающимся блоком. Форму никогда не выбирают в настройках; живые примеры всех форм — в справочнике форм.

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

Каждый файл начинается с SEO-блока, и только потом идёт контент. Порядок обязателен и одинаков во всех файлах всех типов.

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

Группы и их порядок:

Блок со всеми восемью группами и комментариями кладут heron new и heron init в стартовые страницы (index.md, 404.md) и heron page в каждую новую. Новая страница — копия файла с правкой значений; комментарии остаются как есть, их язык задаёт build.notes (ru или en).

Что живёт в site.yaml, а не в файле страницы: имя сайта (по языкам — см. значения по языкам), локаль, twitter:site, og_default_image, реквизиты организации для разметки, ссылки на соцсети для sameAs, суффикс title. В странице — только то, что у неё своё.

Что HERON генерирует сам и в файле не пишется: hreflang на все существующие языковые версии плюс x-default (правила — языки), canonical по собственному адресу, BreadcrumbList, FAQPage при наличии секции faq, datePublished из date, dateModified из updated, запись в sitemap.xml и в llms.txt.

Правила блока:

• порядок групп фиксирован. Человек находит нужное на одном и том же месте в любом файле;
• комментарии обязательны и переносятся из файла в файл без изменений. Это не украшение: сайт ведёт не разработчик, подсказка должна быть под рукой, а не в спецификации;
• группа 2 обязательна на каждой контентной странице. HERON её не читает, но она удерживает правило «один интент — одна страница»: чтобы дописать чужой кластер, надо сначала вписать его туда и увидеть, что ему нужна своя страница;
• мета-тег keywords не выводится. Google игнорирует его с 2009 года, а конкурентам он показывает всю семантику проекта;
• пустые необязательные поля остаются с комментарием, а не удаляются — иначе через полгода никто не вспомнит, что их можно заполнить;
• twitter_* заполняются только когда должны отличаться от og_*; пустые HERON подставляет из Open Graph.

Дальше — контент. Текст до первого заголовка становится секцией intro, затем идут секции вида ## Заголовок {#anchor}, при необходимости с классом модуля: {#red-flags .alert}, {#timeline .timeline}.

## Что это такое {#what}

Короткое объяснение простыми словами…

## Кому подходит {#who}

- Первый признак
- Второй признак

YAML между ---. Это единственный авторитетный список полей: модель страницы (сборка, раздел 6) и образец heron page следуют за ним.

Колонка «ядро» говорит, что HERON делает с полем: да — читает и проверяет сам (E002 — нет обязательного поля или значение не того типа; E001 — фронтматтер не разбирается как YAML); тема — HERON поле не трактует, оно проходит насквозь и доступно шаблону как page.meta.ПОЛЕ. Колонка «группа» — номер группы SEO-блока из таблицы выше.

Поля «тема» в группах 1, 3, 4 и 7 — часть SEO-блока, который кладёт заготовка: их заполняют там, где тема умеет их вывести. HERON не придумывает за тему, как их рисовать, и не ругается на пустые.

redirect_from — рабочий инструмент переезда с WordPress: старый адрес пишется рядом с новым контентом, а не в отдельной таблице, которая разъедется.

Тип выбирает шаблон: страница типа service рисуется theme/templates/service.html (или шаблоном, который тема назвала в types.service.template). Откуда берётся тип, по убыванию силы:

1. поле type в самом файле — для любой страницы, включая одиночную вне раздела (about.md с type: about рисуется templates/about.html);
2. для _index.md — type этого же файла; для обычной страницы — children_type из _index.md её папки;
3. для _index.md подраздела — children_type родительской папки;
4. главная (index.md в корне языка) — home;
5. иначе — page.

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

content/ru/services/_index.md     children_type: service
content/ru/services/roof.md       (type нет: станет service)
content/ru/services/gutters.md    (type нет: станет service)
content/ru/about.md               type: about  →  templates/about.html

Шаблона для получившегося типа в теме нет — E008.

Ключ страницы — путь папок плюс имя файла без расширения (ключ и адрес). У главной — index.md в корне языка — ключ /. Одно правило на всех:

• в меню: nav: {main: ["/", about, services]};
• в ссылке из текста: [на главную](/) — главная на языке страницы;
• в шаблоне: page_of('/') — главная на языке текущей страницы, page_of('services') — любая другая страница по ключу; нет такой — none;
• в подстановках блока schema: {{ pages.home.url }}. Путь подстановки пишется через точки, и / в нём не написать, поэтому здесь главная называется home. Файл home.md в корне языка подстановкам недоступен — HERON предупреждает о нём.

Имя файла задаёт адрес и потому пишется латиницей. Если сайт не на латинице, в меню нужно слово на его языке, а title для этого не годится: он написан под поисковую выдачу и длинный. Поле объявляет сама страница, и живёт оно рядом с ней — у каждого языка свой файл, синхронизировать нечего. У раздела имя объявляет его _index.md.

Пример. Заголовок для поиска длинный, а меню нужно одно короткое слово:

title: "Ремонт крыши в Вене: цены, сроки, гарантия"
h1: "Ремонт крыши"
nav_title: "Крыши"

Не объявлено — HERON берёт имя файла. Одноязычному сайту, где файлы названы словами, заполнять нечего. heron check показывает страницы, которые попали в меню без короткого имени.

date — когда страница вышла, ГГГГ-ММ-ДД, необязательное. Не путать с published: то — флаг «собирать ли страницу вообще», и с updated: то — дата последней правки.

date: 2026-03-14        # вышла
updated: 2026-09-02     # последний раз правили

• разметка: datePublished из date, dateModified из updated (или из build.updated_from). Нет поля — нет ключа в разметке, выдумывать дату HERON не будет;
• лента (seo.feed) сортируется по date, страница без неё — по дате обновления; у записи с date есть дата выхода (published);
• шаблону — page.date (объект даты, {{ page.date.isoformat() }} или свой формат).

Формат дат для машин. В разметку, в lastmod и в Atom дата уходит полной датой со временем и поясом, ISO 8601: так требует Google (dateModified: 2026-10-14 Search Console отклоняет). Время коммита (build.updated_from: git) — как его отдаёт git log -1 --format=%cI, например 2026-10-17T11:30:12+02:00. День без времени — date и updated из фронтматтера, источник file — полночь UTC: 2026-10-14T00:00:00+00:00. Подпись на странице и page.date/page.updated в шаблоне остаются днём; полный момент — page.date_at/page.updated_at.

Проверки. Дата позже момента сборки — предупреждение с путём файла (поисковик сочтёт её ошибкой), при --strict — ошибка. Ручной день сравнивается полночью UTC, ровно тем, что уйдёт в разметку. Обновление раньше публикации — тоже предупреждение; порядок сверяется по дням, так что правка в день публикации ранним утром по местному поясу ошибкой не считается.

updated во фронтматтере — то, что поставил человек. Оно перебивает всё и всегда: есть страницы, где дата — факт, а не метка сборки, и двигать её перекомпиляцией нельзя.

Не поставил — источник выбирает сайт ключом build.updated_from:

Разрешённое значение одно и питает всех троих сразу: подпись под текстом (page.updated в шаблоне), lastmod в карте сайта, dateModified в разметке. Разъехаться они не могут по устройству.

Про file нужно знать главное: время файла — это время записи на диск, а не время правки текста. Копирование без сохранения атрибутов (cp без -a, распаковка архива, выкладка через панель хостинга, свежий клон) ставит всем файлам одно время, и сайт объявит себя обновлённым целиком, не изменившись ни на букву. Поисковик такую карту сайта перестаёт принимать всерьёз, а подпись под текстом врёт уже людям. Поэтому HERON эту подпись распознаёт: если у всех страниц время совпадает с точностью до минуты — это копия, и дата не проставляется вовсе. Отсутствие даты честнее выдуманной.

git таких оговорок не требует: история хранит время изменения содержимого, а не файла, и переживает копирование, клонирование и переезд.

Секция — блок контента с идентификатором. Синтаксис — обычный markdown-заголовок с якорем:

## Что это такое {#what}

Секция — всё от этого заголовка до следующего заголовка того же уровня с якорем или до конца файла. Вложенные заголовки (###) принадлежат секции.

Правила:

• идентификатор: латиница, цифры, дефис;
• порядок секций в файле безразличен;
• один идентификатор дважды в файле — ошибка сборки;
• текст до первой секции считается вводным блоком, доступен теме как intro;
• секция, которую тема не использует, не ошибка — попадает в отчёт heron check;
• секция, которую тема ждёт, а в файле её нет, тоже не ошибка: значение пустое, блок не рендерится, в отчёт идёт строка «тема ждёт секцию X, в файле её нет».

Заголовок секции — это контент, который увидит посетитель. Якорь — это адрес для темы. Их разделение принципиально: заголовок правят, адрес — нет.

Состав секции

Секция приезжает в тему не плоским куском разметки, а разобранной на части. Макет режет страницу мельче, чем заголовок и текст под ним: подводку рисуют одним кеглем, примечание другим, цитату — врезкой.

Нет ни списка, ни таблицы, ни групп — вся секция это body типа «проза», lead и note пустые.

Жирный зачин. Абзац вида **Текст до точки.** Дальше обычный текст разбирается надвое: зачин уезжает в note_title (или в term элемента списка), из тела абзаца он удаляется. Признак — жирный фрагмент в самом начале абзаца, заканчивающийся точкой, двоеточием или тире.

Пункт списка вида **Термин.** Пояснение разбирается в пару {term, text}. Пункт без зачина в таком списке — пара с пустым term. Список, где зачина нет ни у одного пункта, остаётся списком строк.

Разметка внутри значений сохраняется: **жирный** и [текст](ссылка) доезжают до темы разметкой, а не экранированным текстом, включая ссылки внутри жирного фрагмента. Ссылки собираются ещё и отдельным списком links того элемента, где встретились, — тема вправе нарисовать их и в тексте, и строкой чипов.

Вводный блок

Текст до первого заголовка разбирается на абзацы:

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

Некоторые модули ждут не прозу, а данные. Особого синтаксиса нет — всё это валидный markdown, читаемый глазами и в любом редакторе. HERON определяет форму секции по содержимому или по классу в якоре и отдаёт её теме полем section.kind, а разобранные данные — section.data (в шаблоне модуля — items).

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

Таблица форм

Кроме items, у любой секции есть разобранные части — lead, body, note, note_title, callout, links (см. «Состав секции» выше), — и html целиком.

Порядок распознавания

Класс в якоре сильнее содержимого. Без класса форма определяется по первому подошедшему правилу, в таком порядке:

1. table — markdown-таблица со строкой-разделителем;
2. facts — строки ключ | значение без строки-разделителя;
3. steps — нумерованный список;
4. группы ### со списками: ровно две — two-lists, три и больше — checklist. Одна группа со списком формой не считается и уходит дальше по порядку (обычно в list, заголовок группы при этом в items не попадает — нужен класс .checklist);
5. faq — группы ###, ни в одной нет списка;
6. list — маркированный список;
7. callout — цитата >, если списка в секции нет. Секция «список и совет к нему» остаётся list, совет доступен теме как section.callout;
8. prose — всё остальное.

Чем похожие формы отличаются

• checklist и two-lists записываются одинаково — группы ### со списками. Различает их число групп (две или три и больше) либо класс. Смысл разный: две колонки противопоставляют («подходит / не подходит»), чек-лист перечисляет («документы / дополнительно / на приём»), и тема рисует их по-разному;
• facts и timeline записываются одинаково — строки ключ | значение. По содержимому их не различить: без класса это всегда facts, шкала — только с классом .timeline;
• facts и table: facts — это не markdown-таблица, у неё нет шапки и строки-разделителя, ведущая | не нужна; markdown её рендерит абзацем, а HERON разбирает в пары. Как только появляется строка |---|---|, это table с шапкой и любым числом колонок.

Классы в якоре, которые задают форму

Отдельно {.top} на пункте нумерованного списка — признак главного шага (без него top у первого шага). Неизвестный класс — предупреждение, форма определяется по содержимому.

Битый ввод

Разбор ошибается мягко: класс задан, а содержимое ему не подходит (.steps над маркированным списком, .facts без единой строки с |), — секция отдаётся как prose, в отчёт идёт предупреждение «класс не подходит к содержимому». В facts строки без | среди нормальных пропускаются с предупреждением. Валить сборку из-за пропущенной палочки в таблице нельзя.

Шаг подробнее

Шаг может нести метку и ссылки:

1. **[ЧАЩЕ ВСЕГО] Без визита.** Заявка и [проверка документов](/get-started/).

превращается в {n: 1, tag: "ЧАЩЕ ВСЕГО", title: "Без визита", text: "…", links: [{title, href}]}. Метка — фрагмент в квадратных скобках в самом начале пункта, целиком в верхнем регистре; из текста он вырезается. Метки нет — поле пустое.

Тема называет ожидаемую форму

Одна и та же секция на разных страницах бывает разной формы: {#recovery} на одной странице — шкала, на другой — проза. Обе валидны, тема получает section.kind и решает сама.

Тема вправе назвать ожидаемую форму в theme.yaml: uses: ["recovery:timeline"]. Имя формы обязано быть из таблицы выше, иначе тема не загрузится. Расхождение формы на конкретной странице — не ошибка сборки, а строка в отчёте heron check.

Необязательные секции

HERON не знает, какие секции у страниц бывают: это предметная область сайта. Все секции типа — и обязательные по смыслу, и необязательные — объявляет тема в types.ТИП.uses (theme.yaml). Секция из uses, которой нет в файле, — строка в сводке долгов, а не ошибка; секция в файле, которой нет в uses, — строка в отчёте heron check («тема не использует»), это ловит опечатку в якоре.

Эта страница повторяет раздел 4 файла docs/spec/20-data-contract.md из ветки prod. Репозиторий обновляется первым: открыть файл на GitHub.