Everything is written down

Documentation

Q: Where is the documentation for my version?

Inside the image you run. heron docs prints it, so the answer always matches your HERON, even without internet. This site holds a full copy of the latest stable version, and every page links to its source on the prod branch. More in docs in the terminal .

Q: What should I read first?

The eight ideas on this page, then Concepts and First site . After that, open a page only when you need it; how to work with each document tells you which one.

Q: Can I give the docs to an AI agent?

Yes. heron docs --export .heron-docs writes the whole documentation as a folder. The agent reads the rules of your exact version instead of guessing. See HERON for AI .

Q: What happens when I update HERON?

Your sites keep building with the version range they name in site.yaml . To move a site to a newer version, change that line, run a strict build and fix what it reports.

Everything HERON does is written down: on this site, in the repository and inside the image, always matching the version you run. The whole documentation of the repository is copied here in full, in English and Russian: guides, specifications and the roles for AI agents.

The same rules are read by people and by AI agents, so a site built by hand and a site built by an agent follow one contract. Start with the eight ideas below, then read the guides in order.

BasicsNever built a site? Start here: install Docker, pick an editor, learn Markdown, set up git and GitHub, understand the build, point a domain.Working with the docsEvery HERON document: what it answers, who reads it and when. Each one is copied to this site in full, with a link to its latest version in git.ConceptsThe seven ideas HERON rests on: the site folder, the contract, page keys and addresses, languages, the SEO block, sections and forms, themes and the build.First siteFrom an empty folder to a built site in two languages: create it, set up site.yaml, write the home page, add a page, preview it and build for production.Pages and contentHow a HERON page is built and how to add sections, links, related pages, pictures and translations. For whoever runs the site, a person or an AI agent.Theme and designHow a HERON theme is built and how to make your own: theme.yaml, a template per page type, modules, what a template sees, interface texts and images.SEO and languagesWhat HERON writes for search engines and AI by itself, what you fill in, how languages work and how to move from an old site without losing rankings.Build and deployBuild a site for production, pack it into an nginx image, run your own nginx, check every answer code and keep several sites on different HERON versions.Section formsEvery HERON section form with how to write it, the live result, HTML and CSS: text, list, steps, cards, two columns, table, questions, facts, callout.SpecificationsThe open contract between HERON and a site folder, the build, deployment and delivery, copied in full. Every page links to its latest version in git.AI agent rolesOne instruction for any AI agent working on a HERON site: four roles, their inputs and outputs, shared rules and a map of the documentation.Docs in the terminalRead, search and export the documentation of exactly the version you run, offline. Plus the commands that create, check, preview and build a site.GlossaryPlain explanations of markdown, front matter, slug, image, registry, static site, sitemap, canonical, hreflang, schema.org, llms.txt, 301 and more.RoadmapWhat is planned for HERON: an optional data bridge, forms, skills for AI agents, a richer configurator, comparison pages and more search engine settings.

Never done this before? Start here

Start with Basics if you have never built a site. It shows how to install Docker on macOS, Windows or Linux, which text editor to take, how Markdown works on a real page, how to make a GitHub account and what happens when HERON builds your site. Half an hour there, and every other page here reads easily.

Eight ideas to start with

These eight ideas are the whole of HERON in miniature. Open a card for the details and an example; each idea is explained in full in Concepts.

The site is a folder

Your site is an ordinary folder on your computer: pages, photos, data and one settings file. There is no program code in it, so you can open, copy, back up and send it like any other folder.

What is inside: content/ holds the pages, media/ the photos and documents, data/ lists such as prices or team members, static/ files that go online as they are, theme/ the look, site.yaml the settings.
Why it matters: Nothing in the folder can break or get hacked on its own: it is text and pictures. The server only shows the finished pages.
What you do: Create it once with heron new my-site -y, set it up in the configurator, then edit files in any text editor.
Keep it in git: Because it is plain text, git stores every change and you can go back to any day.

heron new my-site -y && cd my-site && ls

What a site folder holds →

HERON is a separate program

HERON is the tool that reads your folder and turns it into a website. It lives outside the site, in a Docker image or a pip package, so the folder stays clean and one HERON serves any number of sites.

How you run it: As one Docker command, or as the short command heron set up once on Get started.
Nothing to install into the site: No plugins, no copied program files. Update HERON and every site benefits, on your terms.
Which version: The first line of site.yaml says which versions fit, for example heron: ">=0.1,<0.2". Another version refuses to build instead of breaking the site.
Its documentation travels with it: heron docs prints the documentation of exactly the version you run, even offline.

Docs in the terminal →

A page is a text file

Every page of the site is one text file. The file name becomes the address: about.md in the folder of your language turns into /about/. You write it in any editor, no special program needed.

The top of the file: A block between two --- lines holds the page settings: title for search results, description for the snippet under it, h1 for the heading on the page.
The rest: Normal text in Markdown: headings, paragraphs, lists, links, pictures.
A new page: Copy a file that looks like what you need, save it under a new name, change the text. The next build makes it a page.
The address: Latin letters, digits and hyphens in the file name: roof-repair.md becomes /roof-repair/.

Pages and content →

A section is a block on the page

A page is cut into sections. Each one starts with a heading and an anchor: ## Prices {#prices}. The heading is what visitors read, the anchor tells the theme which block to draw there.

Example: ## Questions {#faq} followed by ### questions becomes an accordion with questions and answers.
The form is guessed: A numbered list becomes steps, a table becomes a table, three ### groups with lists become cards. You just write.
Order is free: The theme puts sections where it wants them, so moving text around never breaks the layout.
See every form: The forms reference shows the markdown, the result, the HTML and the styles side by side.

Section forms →

Each language is a folder

A second language is a second folder with the same files, for example content/en/about.md and content/de/about.md. Same file name means "these are translations of each other".

Addresses: The main language has no prefix (/about/), others get one (/ru/about/). A translated address is possible with slug:.
For search engines: HERON writes hreflang links, so Google shows the right language in each country.
For visitors: The language switch on every page leads to the same page in the other language.
Adding a language: Add it to languages in site.yaml and run heron init .: the new folder appears with a home page and a 404.

Multilingual websites →

The theme is the look

The theme is how the site looks: templates, styles, fonts, icons in theme/. It never contains your texts, so you can change the design without touching a single page.

Separation: Texts live in content/, the look in theme/. A designer and a writer never get in each other's way.
Ready themes: Start from a theme with demo pages, replace the texts and photos, and the site is yours.
Your own theme: Templates for each page type and one module for each section form. The theme guide explains every rule.
AI agents: A content agent never edits the theme; a designer agent works only in theme/.

Themes →

site.yaml is the settings

One file holds everything about the site as a whole: name, domain, languages, menu, company details, analytics. Every page and the search markup take their facts from here, so a phone number lives in one place only.

Example: site: with domain: example.com and languages: [en, ru], organization: with the company name.
The configurator: heron setup . is a questionnaire: site name, domain, contacts and company details, the kind of organization for search markup, the theme. It writes this file for you, with a hint next to every question.
The version line: The first line pins the HERON version the site needs.
Every key explained: The site.yaml reference lists each block and what it changes.

The configurator →

The build checks everything

heron build turns the folder into a finished site in dist/ and checks it on the way. A broken link, a missing translation or an empty description is reported with the file, the line and what to do.

A normal build: Shows warnings and still builds, so you can look at a draft.
The strict build: heron build . --env prod --strict turns every warning into an error. That is the one that goes online.
Reading an error: It names the code (for example E005), the file and line, and a hint. Common ones are explained in troubleshooting.
Fast: A starter site builds in under a second; a thousand pages in two languages in about 3 seconds.

heron build . --env prod --strict && ls dist

How the build works →

Read in order

Each guide builds on the previous one. Read them once in a row, 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

When you need exact answers

Specifications

The open contract between HERON and a site folder, plus the build, deployment and delivery. Every field, every error code and every rule is written there, so nobody has to guess.

Read when: A guide is not enough, a build stopped with a code, or two people disagree about how something works.
What is inside: Eight pages: the site folder and addresses, the page format, site.yaml, theme.yaml, images and files, the build with all commands and error codes, deployment, delivery.
How to use it: Do not read it in one go. Search for the field or the error code you need and read that part.
Always current: Each page links to the same text on the prod branch in git, where changes appear first.

Specifications →

Forms reference

Every section form with its markdown, the HTML the theme draws, the styles and colour variants, side by side. The fastest way to see what your text will look like before you write it.

Read when: You write a page and want to choose the right form for a block.
What you see: The source text, the live result, the HTML and the CSS behind it, plus colour variants to compare.
Nine forms: Text, list, steps, cards, two columns, table, questions, facts, callout.
Tip: Copy the markdown from the reference into your page and change the words.

Forms reference →

Roles for AI agents

Architect, content and SEO, designer, builder: what each role reads, produces and must not touch, plus what HERON can already do. Hand one of these pages to an agent, and it works by the rules instead of guessing.

Read when: You hand work to an AI agent or brief a person.
Architect: Plans the structure: pages, types, languages, old addresses.
Content and SEO: Writes and fills pages; never touches the theme.
Designer: Makes the theme; never touches the texts.
Builder: Builds, checks and publishes, and reports what is left.

Roles for agents →

HERON versions

HERON is published as images with tags. A tag is the name of a version.

Tag	What it is	Who it is for
prod	The stable version: tested and recommended	Live sites and everyone starting out
beta	The next version, tested on live sites before it becomes stable	Those who want new features earlier
dev	The working version with the latest changes	People who work on HERON itself
0.1.0	An exact release that never changes	Sites that must build the same way for years
latest	The newest exact release	Quick experiments

Questions

Where is the documentation for my version?

Inside the image you run. heron docs prints it, so the answer always matches your HERON, even without internet. This site holds a full copy of the latest stable version, and every page links to its source on the prod branch. More in docs in the terminal.

What should I read first?

The eight ideas on this page, then Concepts and First site. After that, open a page only when you need it; how to work with each document tells you which one.

Can I give the docs to an AI agent?

Yes. heron docs --export .heron-docs writes the whole documentation as a folder. The agent reads the rules of your exact version instead of guessing. See HERON for AI.

What happens when I update HERON?

Your sites keep building with the version range they name in site.yaml. To move a site to a newer version, change that line, run a strict build and fix what it reports.

Documentation

Never done this before? Start here

Eight ideas to start with

The site is a folder

HERON is a separate program

A page is a text file

A section is a block on the page

Each language is a folder

The theme is the look

site.yaml is the settings

The build checks everything

Read in order

Concepts

First site

Pages and content

Theme and design

SEO and languages

Build and publish

When you need exact answers

Specifications

Forms reference

Roles for AI agents

HERON versions

Questions

Where is the documentation for my version?

What should I read first?

Can I give the docs to an AI agent?

What happens when I update HERON?