Preview while you write
The site on your computer, updated on every save.
- Command
heron serve ., then open localhost:8000.- What it does
- Rebuilds the changed pages as soon as you save a file.
- Search engines
- A preview is always closed to indexing.
Basics · 5
How the build works
When you run heron build, HERON reads your site folder and writes a finished website into the dist/ folder. This page shows what happens on the way, so a strange result or an error message makes sense.
No programming here: just the path of one page from your text file to the browser, and how to read what the build tells you.
In plain words
Think of a print shop. You bring the text (your .md files), the photos (media/) and a few instructions (site.yaml). The shop has a layout (the theme). It checks that nothing is missing, sets every page in the layout, resizes the photos for each format and prints the whole edition. The finished edition is the dist/ folder: plain web pages that any hosting can hand out.
The shop works the same way every time. The same folder always gives the same site, on your laptop, on GitHub and on a server.
When you need this page: when the site looks different from what you expected, or the build stops with an error. When you can skip it: while everything works.
One page, from file to browser
- 1
You write a file
For exampleprices.mdin the folder of your language: settings at the top, then the text with sections. Markdown in 10 minutes shows how. - 2
HERON finds it
The file's place gives the page its address:prices.mdbecomes/prices/. On a site with several languages, the copy in the folder of a second language gets that language's prefix, for example/de/…. No list of pages to maintain: a new file is a new page. - 3
HERON reads it
The settings become the title, heading and description. The text is split into sections by the##headings, and each section gets its form: text, list, steps, cards, table, questions. See Section forms. - 4
HERON connects it
The page joins the menu, the breadcrumbs, the list of its folder and the language switch. Every link you wrote in the text is checked. - 5
HERON plans the photos
For each photo the theme can ask for, HERON plans light copies in several sizes and modern formats (WebP, AVIF). Your original stays untouched. - 6
The theme draws it
The page's template puts the sections in their places. The result is one finished HTML file:dist/prices/index.html. - 7
HERON writes the extras
The sitemap for search engines, robots.txt, llms.txt for AI assistants, the news feed, redirects from old addresses and structured data inside each page. - 8
Everything goes into dist/
Pages, photo sizes, styles, scripts. The browser later gets exactly these files, nothing is computed when a visitor opens the page.
What goes in, what comes out
| In your folder | In dist/ |
|---|---|
content/en/index.md | index.html, the home page |
content/en/prices.md | prices/index.html, address /prices/ |
content/de/prices.md (second language) | de/…/index.html, the address with the language prefix |
media/team.jpg | media/… copies in several widths, WebP and AVIF |
site.yaml | Name, menu and contacts on every page, sitemap.xml, robots.txt, llms.txt |
theme/ | The look: the HTML layout, assets/ with styles and scripts |
static/ | Copied as is, for files like a verification file for a search engine |
Three ways to build
A test build
Builds the whole site into dist/ once.
- Command
heron build .- When
- To look at the finished files or test them on another server.
- Warnings
- Shown in the report, the build still finishes.
The final build
The one that goes live.
- Command
heron build . --env prod --strict- Opens the site to search engines
- Only this build allows indexing.
- Strict
- Every warning becomes an error, so a broken link or an empty description never reaches visitors.
Reading the build report
At the end HERON prints a report. A normal one ends with how many files were written:
Files written: 128 → my-site/dist
When something is wrong, HERON names the file, the line, what is wrong and what to do. An error stops the build:
E002 content/en/prices.md:3: description is empty
what to do: add a description of up to 155 characters
A warning does not stop a test build, but stops the final one:
Warnings — 2:
links — 1:
en/about.md:14: link /team/ leads nowhere
other — 1:
en/prices.md: title is longer than 60 characters (71)
How to read it:
- The code (
E002) is the kind of problem. The list of codes is in If something goes wrong and in full in the build specification. - The path and the number are the file and the line to open in your editor.
- "what to do" is the fix. Usually one line.
- Warnings are grouped (links, images, translations…), the most important on top. The full list is saved next to
dist/, in.heron-cache/warnings.txt.
Fix the first error, save, build again. Often one fix clears several messages.
Why it is fast
HERON does the work once, at build time. A visitor gets a ready file, so there is nothing to compute, no database to ask and nothing to break on the server. That is why the starter site scores 100 for performance in Lighthouse on a phone, and why a thousand pages in two languages build in a few seconds.
Photos are the slow part of the first build: every size is encoded once. HERON keeps them in a cache, so the next builds take seconds.
Questions
Do I need to build after every change?
While you write, heron serve builds by itself on every save. The final build is needed only when you publish, and with git push GitHub runs it for you.
My change does not show. Why?
Check that the file is saved and is inside content/. If you look at the live site, it changes only after the final build and the upload. Then refresh the browser with Shift held down, so it does not show a cached copy.
Can I break the site with a wrong file?
A wrong file stops the build with a message, and the live site stays as it was. That is the point of the strict build: a broken version never goes out.
What next?
Put the folder on GitHub: Git and GitHub. The full description of the build is in Build: stages, commands, errors.