Pages and content

A page is like a form you fill in plus a letter you write. The form is at the top: the title for Google, the short description, the heading. The letter is below: your text, cut into blocks by headings. HERON reads both and the theme decides how each block looks.

Example. Below is everything a simple page needs. The part between the --- lines is the form, the rest is the text with one block of questions:

---
title: "Roof repair in Vienna: prices and timing"
h1: "Roof repair"
description: "What we repair, how long it takes and what it costs."
---

We repair flat and pitched roofs in Vienna and around.

## Questions {#faq}

### How long does it take?
Usually two to five days.

You need this page whenever you write or change pages. To see what each kind of block looks like before you write it, open the forms reference.

The file content/en/services/roof.md (a site with default_lang: en, address /services/roof/):

---
# ================= 1. MAIN =================
title: "Roof repair in Springfield"     ← in search results, up to 60 characters
h1: "Roof repair, start to finish"      ← the heading on the page
description: "Patching, re-covering, one-year warranty."
…groups 2–8…
---

Intro: the first paragraph leads in.

The second paragraph is the promise. There is no third.

## What is included {#includes}

- **Inspection.** We come the day you call.
- **Repair.** Patching or full re-covering.

## FAQ {#faq}

### How much does it cost?

We quote after the inspection.

Its Russian translation is content/ru/services/roof.md: the same SEO block with Russian values, the same anchors {#includes} and {#faq}, Russian headings. The comments in the block are in the language chosen at new --notes, not in the language of the page.

Three parts, always in this order:

1. The SEO block is the front matter of eight groups. title, h1 and description are required; the rest when you need it. Every field, its default and what HERON does with it is in one table: page format.
2. The intro is the text before the first heading, no more than two paragraphs: the theme gets them as lead and promise.
3. Sections are ## Heading {#anchor}. Visitors see the heading, the anchor is the address of the section for the theme. You edit the heading freely, the anchor stays.

Copy a ready file or run heron page TYPE NAME: it puts in the full SEO block and a draft of every section the theme expects for that type. Then:

• change title, h1, description; fill in group 2, «key queries». HERON does not read it, but it keeps the rule «one intent, one page»;
• write the intro and the sections. No material for a section? Do not create it: the theme does not draw an empty block, and the «Not filled in» summary after the build shows what is missing;
• build. The page appears in its section's catalog, in the sitemap, in hreflang and in llms.txt by itself.

To delete a page, delete the file. If its address was in search results, add it to redirect_from of the page that replaces it (301) or to gone in site.yaml (410).

A section of the site is a folder with the page of the section itself, _index.md:

content/en/services/_index.md      →  /services/                the catalog
content/en/services/roof.md        →  /services/roof/
content/en/services/gutter.md      →  /services/gutter/
content/ru/services/_index.md      →  /ru/uslugi/               slug: uslugi
content/ru/services/roof.md        →  /ru/uslugi/krovlya/       slug: krovlya
content/ru/services/gutter.md      →  /ru/uslugi/vodostok/      slug: vodostok

A slug in _index.md changes the address of the section and of every page in it: the Russian child pages end up under /ru/uslugi/ by themselves.

It helps to set children_type: service in _index.md: the type of every page in the section, so the theme draws them with its own template. The catalog gets the child pages as page.children, sorted by order, then by h1. There is no pagination: a section is one page; a big section is split into subsections with folders.

A page that belongs to several sections is not put inside any of them. It lies flat and is linked with link fields (below): its address does not depend on how many places show it.

HERON understands the form from the markup and gives the theme parsed data:

Three more come by a class in the anchor: {#flags .alert} is alert-list, {#plan .timeline} is timeline, {#photos .gallery} is gallery. The full table, the order of recognition and exactly what the theme gets: section forms in the specification. To see each form drawn by a theme, open the forms reference.

When HERON guesses wrong

The form is read from the markup, and sometimes the markup says something you did not mean. A class in the anchor always beats the guess:

facts can have a lead-in: a paragraph before the «key | value» lines. The theme gets it as section.lead:

## In short {#quick .facts}

The format in short:

Format | in person
Term   | about a month

If the theme expects another form in theme.yaml (uses: ["docs:checklist"]), the report after the build says «expected checklist, got two-lists». Fix it with a class in the anchor or with the form in uses, whichever is right.

A link to your own page is written from the root, without a language prefix, best of all by its key, the path of the file:

[first site](/docs/first-site/)       in content/en/…  →  /docs/first-site/
[первый сайт](/docs/first-site/)      in content/ru/…  →  /ru/dokumentaciya/pervyj-sajt/
[home](/)                             in content/en/…  →  /
[на главную](/)                       in content/ru/…  →  /ru/

HERON puts in the address in the language of the page, with every slug: you write the same thing, the key, in both languages. No translation? The link leads to the version in the default language, and the report shows a warning. A link to nowhere is a warning with the file and the line. External addresses, /media/… and anchors are left as they are.

In detail: links inside content.

«See also», «related services», «where this is mentioned» are not written as links by hand. The theme declares a link field in theme.yaml, and the page lists file names in it:

related:                 # in the SEO block, group 8
  - gutter
  - slug: inspection
    note: Not sure where to start? Begin here

HERON checks that such pages exist (E006 if not), gives the theme cards with captions and builds the reverse list on the target pages.

In detail: links in theme.yaml.

Everything goes into media/, and links start from the site root:

image: media/themes/clinic.jpg        # preview in the catalog
image_alt: "Home page of the clinic theme"

![The firm theme](media/themes/firm.jpg)

Documents such as a PDF go into media/ too and are linked the same way, as a normal markdown link.

HERON cuts pictures to the proportions and widths of the theme, makes WebP and AVIF and writes in the sizes. Illustrations (with a transparent background) are fitted into the proportion, photos are cropped. A missing file is error E007 with the page name; a file in media/ that nothing links to is a line in the report. Video uses the fields video and video_poster.

In detail: pictures and files.

A translation is a file with the same name in the folder of another language: content/ru/services/roof.md. Its own address comes from slug: krovlya. The link between translations rests on the file name, so changing slug does not break it: both versions get hreflang to each other, and x-default is the English one. A language that is not in site.languages is not read.

In detail: languages in the specification.

• phone, address, hours, social links go into the contact and organization blocks of site.yaml: the theme and the markup take them from there, so the header and the footer never disagree;
• reviews, team, figures go into data/*.yaml;
• the menu goes into nav in site.yaml;
• 410 for removed addresses goes into gone in site.yaml.

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

Next guide: Theme and design.