Specifications

Think of HERON as a builder that follows a recipe book. The specifications are that recipe book: they say which ingredients go into a site folder (pages, photos, one settings file) and exactly what comes out (pages, sitemap, files for search engines and AI). Nothing happens «by magic»: every rule is written here.

Because the rules are written down, three very different helpers can work on one site without stepping on each other: you editing a text, a designer changing the look, and an AI agent adding pages. All three follow the same text.

Example. A rule from the contract says: a file content/en/about.md becomes the page /about/. You do not configure this anywhere. You create the file, and on the next build the page is there.

content/en/about.md   →   https://example.com/about/
content/ru/about.md   →   https://example.com/ru/about/

When you need these pages. When a build stops with an error code, when you want to know exactly what a field does, or when you hand the site to an agent and want it to follow the rules.

When you can skip them. To make and publish your first site, the guides are enough. Come back here when you need the exact answer.

A contract is an agreement between two sides. Here one side is HERON, the other is your site folder. The site promises to keep its files in the agreed places and formats, and HERON promises to build it the same way every time and to say exactly what is wrong when something does not fit.

Because the agreement is written down and public, nobody has to read HERON's code: not a person, not an AI agent. When the documentation and the behaviour differ, that is a mistake in HERON and gets fixed in HERON, together with the text.

The contract is also a promise about time. A site that follows it today builds tomorrow: the stable version of HERON keeps building older sites, and features are added or removed only on purpose, with a version change.

How each section form looks on a real page, with its markdown, HTML and styles: the forms reference.

• One source. The specifications live in the HERON repository, next to the code they describe.
• Same change, same commit. When behaviour changes, its description changes in the same commit. Tests check the sample files, so a stale sample fails before anyone copies it.
• Git first, this site right after. A change lands in the repository first; the copy on this site is updated right after, so the gap between them stays minimal. Every page here ends with a «Source» section that names the file and links to it.
• Permanent links. Links to the prod branch always show the latest stable rules, for example 20-data-contract.md on the prod branch. An exact version, like 0.1.0, keeps its own copy forever.
• Inside the image. heron docs contract prints the version that matches your HERON, even offline. More in docs in the terminal.

HERON is a file-based site builder. The input is a folder with content, images, a theme and one config. The output is a static site in dist/ or a ready nginx image with that site inside.

HERON is not copied into the site. It is delivered as one artifact, the image heron:VERSION (and the same code as a pip package for local work). The site declares the version it needs in site.yaml, and HERON refuses to build a site whose version it does not support.

HERON is built for several different sites from the start: designed around one, it would degrade into that site with abstract variable names.

Stack

Core: Python 3.12 · Jinja2 · markdown-it-py · pydantic · Pillow · click. Package manager uv, linter ruff, tests pytest.

Around it: Docker · nginx · Bash.

Forms service (heron-relay, a separate component, later): FastAPI, no database; SQLite only as a retry spool.

Components

• heron/core/: markdown parser, tree and URLs, link resolution, renderer, image processing;
• heron/modules/: generators: sitemap, robots, llms.txt, JSON-LD, hreflang, redirects, feed;
• heron/contracts/: pydantic schemas of site.yaml, theme.yaml, the front matter and the HERON version;
• heron/cli.py: the commands new, init, check, serve, build, page;
• scripts/site.sh: building, packing into an nginx image, previewing and checking sites from the HERON repository; settings in env/.env.SITE.ENV;
• the site folder: site.yaml, content/, data/, media/, static/, theme/, plugins/. There is no HERON code, no Dockerfile, no compose and no build scripts in it;
• heron-relay: a separate service that receives forms: email, a CRM webhook, Telegram. It is deployed only where there are forms.

Decisions

Recorded in the delivery specification:

• a static site builder instead of Django or Wagtail: a site has nothing to serve at run time;
• the core is delivered as an image with a version, not as a copy in every site repository: three copies of the core mean three diverging builders;
• forms are handled by a separate service, not by HERON: HERON must stay «one pass, no state, exit»;
• a database stores neither content nor site settings. Files are the source of truth. Breaking this rule turns HERON into WordPress;
• design mockups are translated into Jinja2; support.js (69 KB of React runtime) does not go to production;
• the build runs without network: --network=none, nothing is downloaded at build time.

Diagram

                 site folder
   site.yaml · content/ · data/ · media/ · static/ · theme/
                     |
                     v
        heron:VERSION   (image or pip package)
     contracts -> parser -> resolve -> render -> generators
                     |
          +----------+-----------+
          v                      v
        dist/               nginx image
     (to hosting)      (site.sh image on the host)
          |
          v
        nginx  ------>  visitor
                            |
                            v
                     heron-relay (later)
                       |    |     |
                    email  CRM  Telegram

The site does not depend on heron-relay: if the service is down, static pages keep being served, and only form submission is lost.

The architecture text mirrors docs/architecture.md on the prod branch (revised 2026-10-04).