Первый сайт

Ещё нет Docker? Сначала поставьте его: Docker на macOS, Windows и Linux — это минут десять, и в конце есть проверка, что всё работает. Потом возвращайтесь сюда.

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

Что вы сделаете, коротко: создадите папку командой new, напишете HERON название и домен в site.yaml, напишете главную, добавите ещё одну страницу копированием файла, посмотрите результат на localhost:8000 и сделаете итоговую сборку. На каждом шаге есть точная команда: скопируйте, нажмите Enter, посмотрите, что изменилось.

В примере два языка. У вашего сайта может быть один — тогда пропустите шаги про второй язык. Этот гайд показывает и полный диалог heron new в терминале; короткий путь на странице С чего начать — heron new my-site -y, а затем конфигуратор, который спрашивает то же и больше.

Эта страница нужна, когда вы делаете сайт впервые. Пропустите её, если только правите тексты на сайте, который уже кто-то сделал: вам в Страницы и контент.

Все команды ниже запускают HERON из стабильного образа через одну короткую переменную:

H="docker run --rm -it -v $PWD:/site -w /site --user $(id -u):$(id -g) ghcr.io/fmstm/heron:prod"

• -v $PWD:/site — HERON видит только текущую папку. Поэтому путь к сайту в командах — относительно неё: мой-сайт, или ., если вы уже в папке сайта. Путь вида ~/SOURCE/… внутри контейнера не существует — HERON так и скажет;
• -it — чтобы new мог задать вопросы. Без него он молча возьмёт значения по умолчанию;
• --user — иначе файлы окажутся во владении root, и править их вы не сможете.

$H new мой-сайт          # новая папка рядом
$H new .                 # или в текущей — например, в только что склонированном git-репозитории

Папка может быть под git: .git, .gitignore, README и прочее служебное не мешают и не перезаписываются. Любой другой файл — отказ с перечнем того, что мешает.

new задаст несколько вопросов; Enter принимает значение в скобках:

Notes and messages language / Язык пояснений и сообщений
  › (en, ru) [en] ru
Название сайта — как сайт называется для людей: в шапке, в заголовке окна, в разметке
  › [мой-сайт] Workshop
Домен — без https:// и слешей, например example.com. Не знаете — Enter, останется заглушка
  › [workshop.example] workshop.com
Языки сайта — коды через запятую: en или en, ru. Каждый язык — папка content/КОД/
  › [en] en, ru
Основной язык — отдаётся из корня (/about/), остальные — с префиксом (/ru/about/)
  › [en] en

• Язык пояснений — на нём будут комментарии во всех файлах, которые положит HERON, и сообщения на экране. Запоминается в site.yaml (build.notes). Задать заранее: --notes ru или -e HERON_NOTES=ru;
• Без вопросов — флагами: $H new мой-сайт --notes ru --name Workshop --domain workshop.com --lang en,ru -y. Так работают ИИ-агенты и CI.

В конце new печатает, что создал, и блок «Что дальше» с готовыми командами. Что появилось:

мой-сайт/
├── site.yaml                  настройки с комментарием к каждому ключу
├── heron-readme.md            записка: что это за папка — такая есть в каждой папке
├── content/en/index.md        главная с полным SEO-блоком
├── content/en/404.md          страница «не найдено»
├── content/ru/…               то же для каждого языка из ответа
├── media/  data/  static/  plugins/
└── theme/                     стартовая тема: theme.yaml, base.html, шаблоны, модули, стили

Сайт уже собирается, и без единого предупреждения — можно проверить сразу: $H build мой-сайт.

site.yaml — единственная точка правды о сайте. Ответы на вопросы уже там; откройте его и допишите остальное — название на втором языке, суффикс заголовка, меню:

site:
  domain: example.com
  name: Workshop
  name_ru: Мастерская         # название для русских страниц
  theme: main
  default_lang: en            # отдаётся из корня: /about/
  languages: [en, ru]         # второй язык — под /ru/
seo:
  title_suffix: " — Workshop"
  title_suffix_ru: " — Мастерская"
nav:
  main: ["/", about]          # ключи страниц: главная и about — на каждом языке свой адрес

Все ключи с пояснениями — site.yaml в спецификации и образец docs/agents/templates/site.yaml.

$H init мой-сайт

init читает site.yaml и дописывает недостающее: добавили в languages язык de — появятся content/de/index.md, content/de/404.md и theme/i18n/de.yaml. Существующие файлы он не трогает (перезаписать — --force). Если сайт создан с нужными языками сразу, этот шаг не нужен.

init в папке без site.yaml — например, с готовым контентом из другого места — задаёт те же вопросы, что и new, и предлагает языки по папкам, которые уже лежат в content/.

Откройте content/en/index.md. Наверху — SEO-блок: поменяйте title (для выдачи), h1 (для того, кто уже на странице), description (сниппет). Комментарии не удаляйте — они подсказка тому, кто будет править файл после вас.

Ниже — вступление и секции:

We repair roofs since 2010.

We come to measure on the day you call.

## What we do {#about}

- **Roof repair.** Patching and re-covering.
- **Gutters.** Installation and cleaning.

Русская главная — content/ru/index.md: тот же якорь {#about}, свой текст. Якорь — имя секции для темы, он одинаков во всех языках; заголовок переводится.

Какие секции и в каком виде рисует главная, решает тема. Стартовая выводит вступление и все секции подряд; на своей теме у каждой секции будет своё место и свой модуль — Тема и дизайн.

Два способа, результат одинаковый:

cp мой-сайт/content/en/index.md мой-сайт/content/en/about.md   # и поправить значения
$H page page about мой-сайт                                    # тип page, файл content/en/about.md

heron page ТИП ИМЯ кладёт файл с полным SEO-блоком и заготовками всех секций, которые тема ждёт у этого типа. Страница сама появится в карте сайта и llms.txt, а в меню — потому что её ключ about записан в nav.main.

Перевод — файл с тем же именем в content/ru/ ($H page page about мой-сайт --lang ru). Адрес у перевода может быть свой — slug: o-nas в его SEO-блоке:

content/en/about.md   →  /about/
content/ru/about.md   →  /ru/o-nas/      slug: o-nas

Обе версии получат hreflang друг на друга, а пункт меню about на русских страницах сам поведёт на /ru/o-nas/.

$H build мой-сайт && docker run --rm -p 8080:8080 -v "$PWD/мой-сайт/dist:/usr/share/nginx/html:ro" nginxinc/nginx-unprivileged:1.27-alpine

Откройте localhost:8080. После сборки HERON печатает отчёт: сколько страниц по языкам, предупреждения по группам (картинки, связи, ссылки, переводы…) и сводку незаполненных секций. Ошибки останавливают сборку и называют файл и строку.

$H check мой-сайт — тот же отчёт без сборки.

$H build мой-сайт --env prod --strict

--env prod открывает индексацию и включает счётчики из analytics. --strict превращает предупреждения в ошибки: в прод не уедет сайт с битой ссылкой или картинкой без alt. Готовая папка dist/ кладётся на любой хостинг; как собрать образ nginx с сайтом — Сборка и выкладка.

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

Следующий гайд: Страницы и контент.