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

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

Пример. Ниже всё, что нужно простой странице. Часть между строками --- — анкета, остальное — текст с одним блоком вопросов:

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

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

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

### Сколько длится ремонт?
Обычно от двух до пяти дней.

Эта страница нужна всякий раз, когда вы пишете или меняете страницы. Чтобы увидеть, как выглядит каждый вид блока, ещё до того как писать, откройте справочник форм.

Файл content/en/services/roof.md (сайт с default_lang: en, адрес /services/roof/):

---
# ================= 1. ОСНОВНОЕ =================
title: "Roof repair in Springfield"     ← в выдаче, до 60 знаков
h1: "Roof repair, start to finish"      ← заголовок на странице
description: "Patching, re-covering, one-year warranty."
…группы 2–8…
---

Intro: the first paragraph leads in.

The second paragraph is the promise. There is no third.

## What is included {#includes}

- **Inspection.** We come the day you call.
- **Repair.** Patching or full re-covering.

## FAQ {#faq}

### How much does it cost?

We quote after the inspection.

Его русский перевод — content/ru/services/roof.md: тот же SEO-блок с русскими значениями, те же якоря {#includes} и {#faq}, русские заголовки. Комментарии в блоке — на языке, выбранном при new --notes, а не на языке страницы.

Три части, всегда в этом порядке:

1. SEO-блок — фронтматтер из восьми групп. Обязательны title, h1, description; остальное — по надобности. Все поля, их значения по умолчанию и что с ними делает HERON — одна таблица: формат страницы.
2. Вступление — текст до первого заголовка, не больше двух абзацев: тема получает их как lead и promise.
3. Секции — ## Заголовок {#якорь}. Заголовок видит посетитель, якорь — адрес секции для темы; заголовок правят свободно, якорь — нет.

Скопировать готовый файл или выполнить heron page ТИП ИМЯ — он кладёт полный SEO-блок и заготовки всех секций, которые тема ждёт у этого типа. Дальше:

• поменять title, h1, description; заполнить группу 2 «ключевые запросы» — HERON её не читает, но она держит правило «один интент — одна страница»;
• написать вступление и секции. Нет материала для секции — не создавать её: пустой блок тема не рисует, а сводка «Не заполнено» после сборки покажет, чего не хватает;
• собрать. Страница сама появится в каталоге раздела, карте сайта, hreflang и llms.txt.

Удалить страницу — удалить файл. Если её адрес был в индексе, впишите его в redirect_from страницы-замены (301) или в gone в site.yaml (410).

Раздел — папка со страницей самого раздела _index.md:

content/en/services/_index.md      →  /services/                каталог
content/en/services/roof.md        →  /services/roof/
content/en/services/gutter.md      →  /services/gutter/
content/ru/services/_index.md      →  /ru/uslugi/               slug: uslugi
content/ru/services/roof.md        →  /ru/uslugi/krovlya/       slug: krovlya
content/ru/services/gutter.md      →  /ru/uslugi/vodostok/      slug: vodostok

slug у _index.md меняет адрес раздела и всех страниц в нём: русские дети сами оказываются под /ru/uslugi/.

В _index.md полезно задать children_type: service — тип всех страниц раздела, и тема нарисует их своим шаблоном. Каталог получает детей как page.children, отсортированных по order, затем по h1. Пагинации нет: раздел — одна страница; большой раздел делят на подразделы папками.

Страница, которая относится к нескольким разделам, не вкладывается ни в один: её кладут плоско и связывают полями связей (ниже) — адрес не зависит от того, в скольких местах она показана.

HERON сам понимает форму по разметке и отдаёт теме разобранные данные:

Ещё три — по классу в якоре: {#flags .alert} — alert-list, {#plan .timeline} — timeline, {#photos .gallery} — gallery. Полная таблица, порядок распознавания и что именно получает тема — формы секций в спецификации. Как каждую форму рисует тема, показывает справочник форм.

Когда HERON угадывает не то

Форма определяется по разметке, и иногда разметка говорит не то, что вы имели в виду. Класс в якоре всегда сильнее догадки:

У facts можно дать подводку — абзац перед строками «ключ | значение». Тема получит её как section.lead:

## Коротко {#quick .facts}

The format in short:

Format | in person
Term   | about a month

Если тема в theme.yaml ждёт другую форму (uses: ["docs:checklist"]), отчёт после сборки скажет «ждали checklist, пришло two-lists» — исправьте классом в якоре или формой в uses, смотря кто прав.

Ссылка на свою страницу пишется от корня, без языкового префикса, лучше всего ключом — путём файла:

[first site](/docs/first-site/)       в content/en/…  →  /docs/first-site/
[первый сайт](/docs/first-site/)      в content/ru/…  →  /ru/dokumentaciya/pervyj-sajt/
[home](/)                             в content/en/…  →  /
[на главную](/)                       в content/ru/…  →  /ru/

HERON сам подставит адрес на языке страницы, со всеми slug: в обоих языках пишется одно и то же — ключ. Перевода нет — ссылка поведёт на версию языка по умолчанию, в отчёте будет предупреждение. Ссылка в никуда — предупреждение с файлом и строкой. Внешние адреса, /media/… и якоря не трогаются.

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

«Смотрите также», «услуги по теме», «где упоминается» не пишутся ссылками руками. Тема объявляет поле связи в theme.yaml, страница перечисляет в нём имена файлов:

related:                 # в SEO-блоке, группа 8
  - gutter
  - slug: inspection
    note: Not sure where to start? Begin here

HERON проверит, что такие страницы есть (E006, если нет), отдаст теме карточки с подписями и построит обратный список у целевых страниц.

Подробно: связи в theme.yaml.

Всё — в media/, ссылки от корня сайта:

image: media/themes/clinic.jpg        # превью в каталоге
image_alt: "Главная темы для клиники"

![Тема для фирмы](media/themes/firm.jpg)

Документы, например PDF, тоже лежат в media/ и ставятся обычной markdown-ссылкой.

HERON нарежет картинки под пропорции и ширины темы, сделает WebP и AVIF, проставит размеры. Иллюстрации (с прозрачным фоном) вписываются в пропорцию, фотографии кропаются. Нет файла — ошибка E007 с именем страницы; файл в media/, на который никто не ссылается, — строка в отчёте. Видео — поля video, video_poster.

Подробно: картинки и файлы.

Перевод — файл с тем же именем в папке другого языка: content/ru/services/roof.md. Свой адрес — slug: krovlya. Связь между переводами держится на имени файла, поэтому смена slug её не рвёт: обе версии получают hreflang друг на друга, x-default — английская. Языка нет в site.languages — его папка не читается.

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

• телефон, адрес, часы, соцсети — блоки contact, organization в site.yaml: тема и разметка берут их оттуда, и они не расходятся между шапкой и подвалом;
• отзывы, команда, цифры — data/*.yaml;
• меню — nav в site.yaml;
• 410 для удалённых адресов — gone в site.yaml.

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

Следующий гайд: Тема и дизайн.