The answer matches your version

Documentation in the terminal

Q: In which language are the explanations?

Messages of commands come in English by default. --notes ru switches them, and the notes in a new site, to Russian.

Q: Where are all the flags?

In spec 21, section 10: commands and flags .

The HERON image carries its own documentation, so the answer always matches the version you run, even offline. Six commands cover reading the docs, and seven more cover the whole life of a site.

The commands below assume the short heron name from Get started. Without it, put docker run --rm ghcr.io/fmstm/heron:prod in front of docs.

In plain words

The terminal is a window where you type a command and press Enter instead of clicking buttons. HERON lives there: every action — create a site, look at it, build it, read the docs — is one short line. You do not need to learn the terminal itself; you only copy the lines from this page.

Example. You forgot what an error code means. Type heron docs --search "E015" and press Enter: the terminal shows the file and the paragraph that explains it, even without internet.

New to the terminal? How to open it on macOS, Windows and Linux is shown in Docker and the terminal.

Read the documentation

See what is there

The table of contents: where to start, roles for AI agents, guides in order, reference.

heron docs

When: The first time, or when you forget a topic name.
What you see: A short list grouped as on this site: start here, roles for AI agents, guides 01–06, the specifications. Each line shows the topic name to type next.
Next step: Pick a name from the list and run heron docs with it, for example heron docs first-site.
No internet needed: Everything is inside the image you already downloaded.

Read one topic

Prints a whole document as text. Add | less to scroll it page by page.

heron docs theme | less

Topics: readme, agents, concepts, first-site, pages, theme, seo, deploy, contract, engine, deploy-spec, distribution, architecture, and the roles architect, content, designer, builder, capabilities.
Scrolling: With | less press Space for the next screen, b to go back, / and a word to search, q to quit.
Same text as here: heron docs seo prints the guide you can also read at SEO and languages, in the version you run.
Language: The documents are written in Russian; this site has them in English too.

Find an answer

Searches the whole documentation and shows the file, line and the text around it. Works for words and error codes.

heron docs --search "E023"

Typical use: The build stopped with an error code: search for it and read the fix.
What you get: Each match as file, line number and a few lines around it, so you see the answer without opening the file.
Search words too: heron docs --search "slug" finds every place that explains addresses.
Quotes: Put the search in quotes when it has spaces: heron docs --search "redirect_from".

Take a file template

Prints a sample file with every field explained.

heron docs template page.md

Samples: page.md, site.yaml, theme.yaml, structure.md.
Save it as a file: heron docs template site.yaml > site.yaml.sample writes the sample next to your site, then copy the parts you need.
Comments included: Every field has a comment that says what it does and whether you may leave it empty.
Always current: HERON's tests build these samples, so they match the version you run.

Export for your editor or agent

Writes the whole documentation as a folder with working links between files. Open it in your editor or give it to an AI agent.

heron docs --export .heron-docs && ls .heron-docs

Why: The agent reads the rules of exactly your version and does not guess.
Where it goes: A folder .heron-docs in the current folder, with the same file names and working links as in git.
For an agent: Tell it: «Read .heron-docs/AGENTS.md first and follow the content role.»
Keep it out of git: Add .heron-docs/ to .gitignore; export again after you update HERON.

Without the short name

The same commands straight from the image, for a server or a CI job.

docker run --rm ghcr.io/fmstm/heron:prod docs --search "redirect_from"

Note: Only --export needs the site folder mounted, because it writes files.
When it helps: On a server without the heron short name, inside a GitHub Actions job, or on a colleague's machine.
Another version: Replace prod with an exact tag such as 0.1.0 to read the docs of that version.
Export without the short name: Add -v "$PWD":/site -w /site so the files land in your folder.

Commands for a site

Command	What it does
heron new my-site -y	Creates the site folder with demo pages and a theme, without questions; the settings are made in the configurator
heron new my-site	The same, but asks in the terminal for the notes language, name, domain, languages and the main language
heron setup .	The configurator: a questionnaire about the site; saves the answers to site.yaml
heron page page about .	Adds a page of the given type with its full search block and sections
heron serve .	Shows the site at localhost:8000 and rebuilds on every save
heron check .	Lists every problem without building
heron build . --env prod --strict	Makes the final site in dist/, open to search, with every warning as an error
heron --version	Shows the version, branch, commit and build time of your HERON

Errors read like instructions

When something is wrong, HERON prints a code, where it happened, what exactly is wrong and what to do. There are no long technical traces.

heron docs --search "E015"

Add --debug to any command if you are fixing HERON itself and need the full trace.

Questions

Does heron docs need internet?

No. The documentation is inside the image, so it works on a plane and on a server without access to GitHub.

Why is the docs version important?

Because rules change between versions. If your site builds with 0.1, the docs of 0.1 are the right ones, even when GitHub already shows a newer version.

In which language are the explanations?

Messages of commands come in English by default. --notes ru switches them, and the notes in a new site, to Russian.

Where are all the flags?

In spec 21, section 10: commands and flags.