Concepts

Think of HERON as a printing house and your site as a manuscript. You write the manuscript (text files in a folder), the printing house (HERON) turns it into a finished book (the website), and the design of the book (the theme) is chosen separately from the text. You can change the cover and fonts without rewriting a single chapter.

Example. You create the file content/en/prices.md, write a heading and a table of prices in it and run the build. HERON reads the file, sees the address /prices/, draws the table with the theme's table block and adds the page to the menu, the sitemap and llms.txt. You did not touch any code.

Read this page first, before any other guide: every later page uses the words explained here (folder, page, key, address, section, theme, build). New to all of this? Start even earlier with Basics.

HERON is the program heron. It comes as the image ghcr.io/fmstm/heron:TAG or as a pip package. It is never copied into a site and never changed for a site.

A site is a folder that holds not a single line of HERON's code:

my-site/
├── site.yaml       settings: domain, languages, theme, menu, SEO
├── content/        pages in markdown, one folder per language
├── media/          pictures, video, documents
├── data/           yaml lists: reviews, team, company details
├── static/         files served at an exact address: favicon, .well-known
├── theme/          the theme: Jinja2 templates, styles, interface texts
└── plugins/        your own plugins, usually empty

The site says which HERON it needs in the first line of site.yaml: heron: ">=0.1,<0.2". One HERON serves any number of sites, and each site can have its own version.

In detail: the site folder in the specification.

The contract is the agreement between HERON and a site folder: which files go where, which fields a page has, which keys site.yaml accepts, what HERON does by itself and what it answers with an error. It is the same for every site and is written down in the specification. Breaking the contract gives a clear error with a code, a file and a line (E002, E006…), never a silently broken page.

A page is a markdown file. The path of the file gives the address. An example for default_lang: en, languages: [en, ru]:

content/en/index.md                →  /
content/en/about.md                →  /about/
content/en/services/_index.md      →  /services/              the page of the section itself
content/en/services/design.md      →  /services/design/
content/ru/about.md                →  /ru/o-nas/              slug: o-nas
content/ru/services/_index.md      →  /ru/uslugi/             slug: uslugi
content/ru/services/design.md      →  /ru/uslugi/dizajn/      slug: dizajn

A page has two different things that are the same by default:

• the key is the path of the file without .md: services/design. It is the same in every language. HERON links translations by it, and menus and links name the page by it;
• the address is what the visitor sees. The slug field changes it, and the key stays the same. That is why the Russian version lives at /ru/uslugi/dizajn/ while its key is still services/design.

The home page is index.md, its key is /. The «not found» page is 404.md.

In detail: content tree and addresses.

A language is a folder in content/. The list of languages and the default one are set in site.yaml:

site:
  default_lang: en       # served from the root: /about/
  languages: [en, ru]    # the others get a prefix: /ru/o-nas/

A translation is a file with the same name in the folder of another language. It can have its own address (slug). Translated pages get hreflang links to each other, and x-default points to the version in the default language. Changing default_lang changes the address of every page.

In detail: languages in the specification.

Every page file starts with an SEO block: YAML between two --- lines, split into eight groups with comments: main, key queries, Open Graph, Twitter, schema.org, card, service fields, links. Three fields are required: title, h1, description. The rest you fill in when you need them; empty fields stay commented out.

The starter pages come with the full block, and heron page puts it into every new page. A new page is a copy of a file with new values.

In detail: page format.

After the SEO block comes the text. The text before the first heading is the intro. Then come the sections:

## How we work {#how}

1. **Request.** You write or call.
2. **Meeting.** We talk the task through.

{#how} is the anchor, the address of the section for the theme. The order of sections in the file does not matter: the theme puts each one in its place by its anchor. HERON understands the form of a section from its markup: a numbered list is steps, ### Question? is an FAQ, key | value lines are facts, a table is a table. There are twelve forms in all.

In detail: sections and forms, and the forms reference shows each one drawn by a theme.

The theme is the theme/ folder: Jinja2 templates, modules, styles, interface texts. It decides how the site looks; the content decides what it says.

The page type picks the template: a page of type service is drawn by theme/templates/service.html. The type is set by the type field in the file or by children_type in the _index.md of its section. The home page is home, the default is page. In theme/theme.yaml the theme describes its types, their sections, links between pages and image proportions.

In detail: theme.yaml in the specification and the theme guide.

heron build reads the folder, checks it against the contract and builds dist/: the HTML of every page, sitemap.xml, robots.txt, llms.txt, JSON-LD markup, cut images, the 301 and 410 maps and the nginx config. A development build (the default) is closed to search engines; the live one is --env prod. The result is either a folder for any hosting or an nginx image with the site inside.

In detail: build stages and the build and deploy guide.

This page mirrors docs/guide/01-concepts.md from the prod branch. The repository is updated first, so the file there is always the latest version.

Next guide: Your first site.