SEO и языки

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

Что заполняете на каждой странице: три строки вверху — title (что люди видят в Google), description (две строки под ним) и h1 (заголовок на странице). Что заполняете один раз: домен, языки и реквизиты компании в site.yaml.

Пример. Вы пишете title: "Ремонт крыши в Вене: цены и сроки". Google показывает ровно это синей ссылкой, а строгая сборка останавливается, если вы забыли описание, поэтому пустой сниппет в интернет не попадёт.

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

Ничего из этого не пишется руками и не лежит файлом — собирается на каждой сборке из страниц и site.yaml, поэтому не устаревает:

На каждой странице — группа 1 SEO-блока:

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

Остальные группы — по надобности: своя картинка для соцсетей (3), уточнение разметки (5), картинка в каталоге и alt к ней (6), дата публикации, noindex (7), старые адреса (8).

Один раз на сайт — в site.yaml:

site:
  domain: example.com
  name: Workshop
  name_ru: Мастерская        # значение для русских страниц
seo:
  title_suffix: " — Workshop"
  title_suffix_ru: " — Мастерская"
  og_default_image: media/themes/heron.jpg
  llms_txt: true
  llms_note:                 # факты о сайте для нейросетей, по языкам
    en: |
      Phone for bookings: …
    ru: |
      Телефон для записи: …
contact: { phone: "…", city: "…" }
organization: { name: "…" }
schema:
  entity:                    # сквозной узел: кто стоит за сайтом
    "@type": Organization
    name: "{{ organization.name }}"
    telephone: "{{ contact.phone }}"
analytics:
  ga4: G-XXXXXXX

{{ … }} в schema — подстановки из того же site.yaml: адрес и телефон живут в одном месте и не расходятся между вёрсткой и разметкой. Подробно — блок schema.

Цены в разметке запрещены по умолчанию (E020): если сайт не показывает стоимость на страницах, она не должна утечь в JSON-LD. Разрешить — seo.allow_prices: true.

Дата обновления. lastmod и dateModified берутся из updated во фронтматтере, а если его нет — из источника build.updated_from: git (дата последнего коммита файла), file (время файла) или manual (только руками). Ручное updated сильнее источника: если вписать его всем страницам при переносе, git-даты работать перестанут. Отчёт после сборки покажет, у скольких страниц так вышло. Поисковику даты уходят полным ISO 8601 с поясом: из git — время коммита (2026-10-17T11:30:12+02:00), ручной день — полночь UTC (2026-10-14T00:00:00+00:00); на странице подпись остаётся датой. Дата из будущего и обновление раньше публикации — предупреждения, при --strict ошибки.

schema.org — общий словарь, которым сайт объясняет поисковику, о чём страница: клиника, человек, статья, список вопросов. HERON пишет его в формате JSON-LD — небольшим блоком данных внутри страницы.

• Один узел на весь сайт. Блок schema.entity в site.yaml описывает, кто стоит за сайтом, и попадает на каждую индексируемую страницу.
• Подстановки, а не копии. {{ contact.phone }} берёт телефон из того же site.yaml, что и тема, поэтому разметка и страница не расходятся.
• Язык подставляется сам. На русской странице поле адреса получает русское значение.
• Пусто — значит нет. Поле без данных не попадает в разметку, пустым оно не пишется.
• Проверка при сборке. Разметка каждой страницы должна быть корректным JSON, а тип, который обещала тема, — на месте.

Конфигуратор спрашивает, о какой организации или человеке сайт, и заполняет этот блок за вас.

llms.txt — обычный текстовый файл в корне сайта: короткое описание и список важных страниц, по строке на каждую. ИИ-помощники читают его, чтобы быстро понять сайт. HERON собирает его из ваших страниц при каждой сборке вместе с llms-full.txt, где лежат полные тексты.

• На сайте с несколькими языками у каждого языка свой файл — llms-en.txt, llms-ru.txt, а llms.txt ссылается на них.
• Факты, а не указания. Заметка llms_note — для фактов о сайте. Строки, которые пытаются управлять чужим ИИ, выглядят как атака, и сайт теряет доверие целиком.

Что такое llms.txt и как его сделать

• Перевод — файл с тем же именем в папке языка; hreflang и переключатель языков появятся сами.
• У перевода может быть свой адрес (slug) — связь держится на имени файла.
• Один язык — нет hreflang, нет языковых карт и llms-ЯЗЫК.txt: лишнее не генерируется.
• Нет перевода — в отчёте предупреждение, в переключателе язык погашен; ссылки на такую страницу с других языков ведут на версию языка по умолчанию.
• Основной язык пуст — боевая сборка остановится (E021).

Цель — ни один проиндексированный адрес не должен отдать 404.

1. Выгрузите старые адреса — из карты сайта, Search Console, логов.

2. Адрес переехал — впишите его в SEO-блок новой страницы:

   redirect_from:
     - /старая-страница/
     - /%D1%81%D1%82%D0%B0%D1%80%D0%B0%D1%8F/
   

   Кириллица и percent-encoding нормализуются: обе формы выше — один адрес, 301 сработает на любую, со слешем и без.

3. Адреса больше нет — в gone в site.yaml. Сервер ответит 410, и поисковик выкинет адрес быстрее, чем после 404:

   gone:
     - /sample-page/        # ровно этот адрес
     - /wp/*                # всё под /wp/
     - /?p=*                # главная с параметром p
   

4. Соберите. HERON проверит, что старый адрес не совпадает с живой страницей, не ведёт в два места и не образует цепочку (E009), а 410 не пересекается со страницами и редиректами (E022).

5. Проверьте на образе: scripts/site.sh САЙТ smoke prod поднимает nginx и проверяет ответы 200, 404, каждый 301 и каждый 410 — Сборка и выкладка.

Подробно: старые адреса в спецификации и переезд с существующего сайта.

heron build мой-сайт --env prod --strict

--strict превращает предупреждения в ошибки: битая ссылка, картинка без alt, незаполненная обязательная связь не уедут в прод. Отчёт сборки считает страницы по типам разметки — видно, что JSON-LD доехал до всех.

Эта страница повторяет docs/guide/05-seo.md из ветки prod, с двумя короткими дополнениями для сайта: schema.org и llms.txt простыми словами. Репозиторий обновляется первым, поэтому там всегда самая свежая версия.

Следующий гайд: Сборка и выкладка.