A map of the documentation

How to work with each document

HERON has about twenty documents, and each one answers its own kind of question. This page tells you which one to open, who it is written for and when to read it.

Every document is copied to this site in full, so you can read it here. The same files live in the repository, where they are updated first (the prod branch always shows the latest stable version), and inside the image: heron docs with the topic name prints the one you need.

In plain words

HERON has many documents, like a cookbook with a separate chapter for every kind of dish. You never read a cookbook from cover to cover: you open the chapter you need. This page is the table of contents that tells you which chapter answers your question.

Example. The build stopped with «E007». You do not read the guides from the start: the table below says «What does this error code mean? → Build, error codes», you open that page and find the line for E007.

You need this page when you do not know where to look. You can skip it if you are following the guides in order: each one links to the next.

Which document answers what

Your question	On this site	In the terminal
What is HERON, how do I start?	[Get started](/get-started/)	heron docs readme
I am an AI agent, where do I begin?	[Roles for agents](/docs/agents/)	heron docs agents
What are the basic ideas?	[Concepts](/docs/concepts/)	heron docs concepts
How do I make my first site?	[First site](/docs/first-site/)	heron docs first-site
How do I write pages and sections?	[Pages and content](/docs/content/)	heron docs pages
Which form fits my block?	[Forms reference](/docs/forms/)	heron docs contract
How do I make a theme?	[Theme and design](/docs/theme/)	heron docs theme
What about search engines and moving?	[SEO and languages](/docs/seo/)	heron docs seo
How do I publish?	[Build and publish](/docs/deploy/)	heron docs deploy
What exactly is allowed in a file?	[Specifications](/docs/spec/)	heron docs contract
What does this error code mean?	[Build, error codes](/docs/spec/engine/#errors)	heron docs --search "E015"
Can HERON already do X?	[What HERON can do](/docs/agents/capabilities/)	heron docs capabilities

Start here

README

The first look at HERON: what it is, a quick start in one command, how one HERON serves several sites. On this site the same story is told by the home page and «Get started».

Who: Everyone, on the first day.
When: Before anything else, and when you explain HERON to someone.
What you learn: That a site is a folder of text files, HERON is a separate program that builds it, and one command starts everything.
How long: Five minutes. It is the shortest document of all.
Try it: Run heron docs readme to read the same text in your terminal, offline.

Get started · README in git

AGENTS.md

One instruction for an AI agent that got a link to the repository and a task about a site: four roles, common rules, a map of the docs.

Who: Claude Code, Codex and any other agent, and people who brief them.
When: The agent reads it first, before any other file.
What is inside: The four roles (architect, content and SEO, designer, builder), what each one reads and produces, the rules all of them follow and a map of every document.
How to use it: Give the agent the repository link, or run heron docs --export .heron-docs and point it at that folder.
Why it helps: The agent stops guessing: it knows which folders it may touch and which check proves the work is done.

Roles for agents · AGENTS.md in git

CHANGELOG

What changed in each version: build, contract, commands, documentation. Release notes also appear in the project news.

Who: Anyone who updates HERON or a site's version range.
When: Before you change the heron: line in site.yaml.
What is inside: Every version with its changes grouped by build, contract, commands and documentation.
How to read it: Find the version you move to and read its «Contract» part: that is what may need a change in your files.
After reading: Change the version line, run heron build . --env prod --strict and fix what it reports.

CHANGELOG in git

Guides, in order

Each guide builds on the previous one. Read them in order once, then come back to the one you need.

1
Concepts

Folder, page, key, address, section, languages, theme, settings, build: the ideas everything else rests on.
Concepts
2
First site

From an empty folder to a built site in two languages.
First site
3
Pages and content

The search block at the top of a page, sections and their forms, links, images, translations.
Pages and content
4
Theme and design

theme.yaml, templates, modules, interface texts, images in a theme.
Theme and design
5
SEO and languages

What is written for search engines by itself, what you fill in, languages, moving from an old site.
SEO and languages
6
Build and publish

Two outputs, a folder or an image; site environments; several sites; the checks before going live.
Build and publish

Specifications

The exact rules. Read a section when a guide is not enough or when two people disagree about how something works. All specifications →

20 · Contract

The agreement between HERON and a site folder. On this site it is split into five pages: site folder and addresses, page format, site.yaml, theme.yaml, images and files.

Who: Content editors, designers, agents.
When: You need the exact name or meaning of a field.
Example question: «Can a Russian page have its own address?» The site-folder page answers: yes, with slug:, and shows the result.
What it fixes: Disputes. If a page and the contract disagree, the contract wins and the page is fixed.
How big: Long, so search it for the field you need instead of reading it in one go.

Spec 20 in git

21 · Build

The steps of a build, what a template sees, every command and every error code with its fix.

Who: Theme developers and whoever fixes a failed build.
When: The build stopped with a code, or a template needs a value.
Error codes: Every code (E002, E005, E015…) has a line: what happened and what to do. Start there when a build stops.
Commands: Every command and flag of heron, with examples.
For theme authors: The full list of what a template receives: the page, the site, the sections, the helpers.

Build · Spec 21 in git

22 · Deploy

Containers, update scripts, CI, nginx, moving an old site with its redirects, backups.

Who: Whoever runs the server or the GitHub repository.
When: Before the first publication and before a move.
What is inside: How the site runs in a container, how updates arrive, how CI builds the image, how nginx is set up and how an old site moves without losing its addresses.
Example: Moving from WordPress: the table of old addresses becomes real 301 redirects in the nginx config.
Not needed when: You publish static files to GitHub Pages; then Build and publish is enough.

Deploy · Spec 22 in git

23 · Delivery

How HERON is delivered: the image, the pip package, tags, the site image and its checks, forms, security of the build.

Who: Whoever chooses a version or builds images.
When: You pin a version or set up a server.
What is inside: The image tags (prod, beta, dev, exact versions), the pip package, the image of a site with nginx, the smoke check that proves it opens, and the security rules of the build.
Example: Pin ghcr.io/fmstm/heron:0.1.0 on a site that must build the same way for years.
Read with: The versions table on the docs home page.

Delivery · Spec 23 in git

Roles for AI agents

Work on a site splits into four roles. One agent can go through all of them, or get only one and hand its result on. All roles →

Architect

Designs the structure of a new site from an old one or from a brief: pages, keys, types, languages, a table of old addresses.

Output: A structure document, a draft site.yaml, questions for the owner.
Input: An old site, its sitemap or a short brief from the owner.
Does: Lists every page, decides its key, type and language, and decides for every old address: redirect (301) or gone (410).
Does not: Write texts or design the theme; it hands those on.

Architect

Content and SEO

Writes pages, fills the search block, adds translations and old addresses.

Output: Files in content/, pictures in media/, a list of missing facts.
Input: The structure from the architect, or an existing site, plus facts from the owner.
Does: Copies a page file under a new name, fills title, h1, description, writes the sections, adds translations.
Does not: Touch theme/, scripts or the structure in site.yaml; never invents phone numbers or prices.

Content and SEO

Designer

Builds the theme: a template for each page type, a module for each block form.

Output: The theme/ folder that draws every page, even with incomplete content.
Input: The page types and their sections, plus a mockup or a description of the look.
Does: Writes templates, one module per section form, interface texts in every language, styles.
Does not: Put any text of the site into the theme: texts stay in pages, facts in site.yaml.

Designer

Builder

Assembles everything, runs the strict build, makes the image and the report.

Output: A site that builds with --env prod --strict and answers with the right codes.
Input: Everything the other roles made, or just «build it by the structure».
Does: Runs the strict build until it is clean, makes the image, runs the smoke check, publishes.
Reports: What was done, what content is still missing, which warnings were left on purpose.

Builder

What HERON can already do

A list by task. Read it before asking for a new feature: almost everything a site needs is already there.

Who: Architects, agents, anyone planning a site.
Example: «Can a page belong to two sections?» Yes, through links between pages, without copying it.
Why read it first: Most «new feature» requests are already covered; this saves days.
Honest list: It also says what HERON does not do on purpose, and why.

What HERON can do

File templates

Samples of a page, site.yaml, theme.yaml and a structure plan, every field explained. Tests check them, so they never go stale.

Who: Anyone creating a file from scratch.
What is there: A page with all eight groups of the search block, a full site.yaml, a theme.yaml and a structure plan.
How to use them: Copy a template, keep the comments, fill in the values. The comments explain each field.
Never stale: HERON's tests build these templates, so they always match the current version.

Templates in git

Notes inside your site folder

heron new puts a short note named heron-readme.md into the site folder and into each folder inside it: content, media, data, static, theme. Each note says what belongs in that folder and what does not.

Read them when you open a folder for the first time. HERON never turns them into pages, so they can stay in the repository. You can write them in English or Russian: heron new --notes ru picks the language.

Questions

Do I need to read everything?

No. Read the eight ideas on the documentation page and First site, then open a document only when a question comes up. The table at the top of this page tells you which one.

This site, git and my image differ. Which is right?

For your site, the one in your image: it matches the HERON that builds your site. Git on the prod branch shows the latest stable version and is updated first; this site follows right after.

The docs say one thing and HERON does another. What now?

That is a mistake in HERON, not in your site. Write down the file, the command and what happened, and report it in the repository.

Are the docs only in Russian?

The documents in the repository are written in Russian. This site carries the full text in English and Russian, so you and your AI agent can read either.

How to work with each document

In plain words

Which document answers what

Start here

README

AGENTS.md

CHANGELOG

Guides, in order

Concepts

First site

Pages and content

Theme and design

SEO and languages

Build and publish

Specifications

20 · Contract

21 · Build

22 · Deploy

23 · Delivery

Roles for AI agents

Architect

Content and SEO

Designer

Builder

What HERON can already do

File templates

Notes inside your site folder

Questions

Do I need to read everything?

This site, git and my image differ. Which is right?

The docs say one thing and HERON does another. What now?

Are the docs only in Russian?