HERON
Get started

Reference

Section forms

Every section of a page has a form: plain text, a list, steps, cards, a table and so on. You never pick the form in a setting. HERON reads how the section is written and tells the theme which form it is, and the theme draws each form with its own module.

Below is every form this site's theme draws. Each one shows how to write it, the live result, the HTML the theme produces and the CSS behind it. Switch the colour dots to see how the same block looks in another palette.

How HERON picks a form

A section starts with a heading and an anchor: ## Title {#anchor}. Everything up to the next heading of the same level belongs to it. HERON looks at what is inside and checks the rules in this order, the first match wins:

  1. a markdown table with a separator line is a table;
  2. lines key | value without a separator are facts;
  3. a numbered list is steps;
  4. ### groups that each have a list: exactly two are two columns, three or more are cards;
  5. ### groups without lists are questions;
  6. a bulleted list is a list;
  7. a quote > without a list is a callout;
  8. anything else is text.

A class in the anchor overrides the rules: {#tips .list}, {#guide .prose}, {#plans .checklist}. If the class does not fit the content, the section falls back to text and the build report says so. The full rules are in the contract.

Form · prose

Text

Plain paragraphs, subheadings, links and code. Use it for explanations that read top to bottom. A long text section keeps its ### subheadings when you add the .prose class.

Why a folder is enough

A HERON site is a folder of text files. You can read, copy and keep it in git, and nothing runs on the server except nginx.

What is inside

Pages in content/, photos in media/, settings in site.yaml.

The theme receives the whole section as HTML (section.html) and draws it with modules/prose.html.

Form · list

List

A bulleted list. When an item starts with a bold term ending in a full stop, HERON splits it into a term and its explanation, and the theme can draw the term apart.

What you get on the first build

Sitemap

Every page, with the date it last changed.

llms.txt

A short map of the site for AI assistants.

A real 404

In every language, with the right answer code.

The theme receives items: a list of pairs term, text, links, and draws them with modules/list.html.

Form · steps

Steps

A numbered list. Each item is a step with a title, text and links. A tag in capitals in square brackets at the start becomes a label on the step.

From a folder to a live site

  1. 1

    Create

    heron new my-site -y makes the folder with demo pages.
  2. 2

    Fill in

    Change the texts, add photos, copy a page for a new one.
  3. 3

    Publish When ready

    Build files or an image and publish it the way you chose.

The theme receives a list of steps n, tag, title, text, links and draws them with modules/steps.html.

Form · checklist

Cards

Three or more ### groups, each with a list. Every group becomes a card: its first paragraph is always visible, the list and anything after it open on click. A summary that starts with "Available.", "Coming soon." or "Paid." gets a badge.

What HERON does for you

The theme receives groups title, html, items and draws them with modules/cards.html. Card rows look even with 2, 3, 4, 6 or 8 cards.

Form · two-lists

Two columns

Exactly two ### groups with lists. Written like cards, but meant as a contrast: suits / does not suit, before / after.

Is HERON for you

Good fit

  • Business sites, blogs and documentation.
  • Several languages.

Not the goal

  • An online shop with a cart.
  • Editing pages in a browser.

The theme receives the same groups as cards and draws them side by side with modules/cards.html.

Form · table

Table

A markdown table with a separator line. Any number of columns. In this theme a cell that starts with + is highlighted as the strong side, and code in backticks stays code.

Ways to store and publish

WayYou doCosts
git pushEdit and pushFree on GitHub
Docker HubBuild and push an imageA server
Static filesBuild and copyFree on Pages

marks where a tool is strong.

The theme receives head and rows and draws them with modules/table.html.

Form · faq

Questions

### groups without lists: the heading is the question, the text below is the answer. HERON also adds FAQPage structured data for search engines from this section.

Questions

Do I need to know how to code?

No. Pages are text files with a few simple marks.

Is it free?

Yes. HERON is open source under AGPL-3.0.

The theme receives pairs q, a and draws them as an accordion with modules/faq.html.

Form · facts

Facts

Lines key | value without a table header. Short data: format, price, duration, address.

In short

Licence
AGPL-3.0
Image
ghcr.io/fmstm/heron:prod
Languages
as many as you need

The theme receives pairs key, value and draws them with modules/facts.html.

Form · callout

Callout

A quote > in a section without a list. One important note that should stand out from the text around it.

Before you publish

Run the strict build first: it stops on any warning, so a broken link never reaches visitors.

The theme receives the quote as HTML and draws it with modules/callout.html.

Theme blocks by anchor

Some blocks of this site's theme are not separate forms: the theme recognises them by the anchor.

  • {#publish} or {#ship} with cards becomes tabs with a diagram beside them.
  • {#story} with steps becomes slides that turn as you scroll.
  • {#llms-gen} draws the llms.txt generator.
  • {#learn} on the home page becomes a list of link cards.

Another theme may draw the same sections differently: the content stays, the look changes. How to add a module of your own is in Theme and design.