Fast websites tuned for search and AI

From one folder to a live site

Your site is an ordinary folder of files. HERON creates the right structure in it, reads the content and builds the site from it. On your computer you only need Docker. To publish, you need hosting for the finished files, or a server or service that runs Docker containers. Never heard of Docker? Install it in ten minutes. Every step below is one command with a clear result.

1
Create the site
The command takes the latest stable HERON image, and the image creates the my-site folder: the content structure, demo pages, a theme and site.yaml, the settings file. Without the -y flag HERON first asks a few questions: the language you prefer to work in, the name, the domain, the languages of the site and the main one. You can answer them right away, or add -y as in the command below and fill everything in later in the configurator, where any answer can be changed. The other ways to run HERON are collected on one page¹.
```
docker run --rm -it -v "$PWD":/site -w /site --user $(id -u):$(id -g) ghcr.io/fmstm/heron:prod new my-site -y
```
Your first site How a site folder works New to this? Start here
2
Set it up in the configurator
The configurator is a questionnaire. You fill in the site name and domain, the reference data (contacts, company details, who you are: a company, a doctor, a lawyer, a private person), choose a theme and the other settings. The configurator fits the folder structure to your project and saves the answers to site.yaml. Search markup, the sitemap and llms.txt are built from the same answers.
```
cd my-site && heron setup .
```
What the configurator asks All settings in site.yaml
3
Fill the pages
Open the site folder in a text editor and look at how it is laid out: content/ holds the texts of the pages (one folder per language of your site), media/ holds photos and video, site.yaml holds the settings and connections to outside services such as Google. Open the home page file: at the top is its description for search engines, below are the blocks of the page. A new page is a copy of a file under a new name, with your text. Write it yourself or with an AI agent and see the result in the preview right away.
```
heron serve .
```
Markdown in ten minutes Pages and content How text becomes a block of the page
4
Publish
Build the final version. The strict check stops on any warning and names the file and line, so a broken link or an empty description never reaches visitors. The final version is either ready files or an image of the site, and you can publish it in any of the ways below.
```
heron build . --env prod --strict
```
How to store and publish What happens during the build

~/sites

my-site/ ├─ site.yaml the only config: name, domain, languages, theme, menu ├─ heron-readme.md a note in every folder: what goes here ├─ content/en/ ru/ pages in markdown, a folder per language ├─ media/ photos and files, cut to every size on build ├─ data/ reviews, team, numbers in yaml ├─ static/ files copied as they are └─ theme/ how the site looks: templates, styles, strings

HERON configurator · my-site

Site name iShown in titles, the header and the markup.

Domain iCanonical URLs, sitemap and hreflang are built from it.

Organization iName, address and phone go to schema.org on every page.

Languages iThe first one is the default. Each language gets its own URLs.enruukde

Theme iComes with demo pages. Watch the 30-second video.heronclinicfirm

Publish with igit push makes the first commit and adds the image workflow.dist/Docker Hubgit push

Git repository iGitHub builds the image from here on every push.

Saved to site.yaml

localhost:8000 · preview

dist/ · static filesany hosting or your own nginx

nginx image → Docker Hubprivate repository, your token

git push → GitHub → imagean image on every push, update on your OK

step 1 of 4

Choose how to store and publish your site

The final build is either ready files for any hosting, or an image: the whole site together with a small web server that runs on any machine with Docker. An image can be stored on GitHub, on Docker Hub or in your own registry. There are three ways to publish today, and more will come. You can change your mind at any time: the site folder stays the same.

gitDocker HubReady files

You keep the site in a git repository on GitHub, and the image builds itself. After the first setup you only edit files and send the changes: GitHub builds the site, checks it and puts a fresh image into its own storage. No separate account for images is needed.

git add . && git commit -m "New services page" && git push

Once. Create a free account and an empty repository on github.com and send the site folder there. The configurator adds the build file .github/workflows/image.yml. Git and GitHub from zero
Edit. Change a page file or add a new one: on your computer, right on github.com or with an AI agent.
Send. The command above saves the change in the history with a short label and sends it to GitHub.
Build. GitHub Actions runs HERON with the strict check, builds the image and test-runs it. A broken link stops the release here, and the Actions tab shows the file and line.
Result. The fresh image is in GitHub Packages, and free hosting such as GitHub Pages takes the new files. A server pulls the new image with one command.
Undo. Every send is a step in the history: git revert brings the previous version back with the next send.
Paid add-on. HERON Agent updates the site on your server from every new image by itself.

Full guide: storing in git and building the image →

You edit a .md pageYour step
git commit and git pushYour step
GitHub Actions builds the siteAutomatic
It checks that the site opensAutomatic
The image goes to the registryAutomatic
The server takes the new image^¹Your step
You open the site and check itYour step

Your step Automatic · 3 of 7 steps run by themselves

¹ With HERON Agent (paid) this step runs by itself: the Agent pulls the new image, swaps the container and rolls back if the check fails. On GitHub Pages it is automatic anyway.

You build the image yourself and keep it in your own repository on Docker Hub. Any server with Docker can run it. Good if you have your own server and want to decide yourself when each version goes live.

heron build . --env prod --strict && curl -fsSL https://raw.githubusercontent.com/FMSTM/HERON/prod/Dockerfile.site | docker build -t you/my-site:prod -f - dist && docker push you/my-site:prod

Account. Sign up at hub.docker.com and create a repository, for example you/my-site. A private one keeps the site hidden until it is ready.
Token. Account settings → Personal access tokens → Generate. It is the password for docker login; keep it out of the site folder and out of git. Make two: read and write for the computer where you build, read-only for the server.
Sign in. Run docker login -u you and paste the token: once on your computer and once on the server.
Build and send. The command above builds the site, packs it into an image with the HERON recipe and sends it to Docker Hub.
On the server. Pull the new image and restart the container: docker pull you/my-site:prod, then start it with the command from the guide. The site is back in a few seconds.
Paid add-on. HERON Agent pulls every new image from your Docker Hub with your key and swaps the container by itself.

Full guide: images and Docker Hub →

Docker Hub account and a tokenYour step
Sign in with the token: here and on the serverYour step
You build the siteYour step
You pack it into an image and push itYour step
The server pulls and runs the image^¹Your step
The new site is liveAutomatic
You open the site and check itYour step

Your step Automatic · 1 of 7 steps runs by itself

¹ With HERON Agent (paid) the last steps run by themselves: it pulls the image from your Docker Hub with your key and updates the container.

The simplest hosting and the most manual way: you build the site and copy the finished files to the hosting on every update. Any hosting works, paid or free, even the cheapest one with FTP access.

heron build . --env prod --strict && ls dist

Build. The command above makes the dist/ folder: every page, image, the sitemap and llms.txt. This folder is the whole site.
Check. Open the finished site at localhost:8080 before it goes live, with one command from the guide.
Copy. Upload dist/ through the file manager of your hosting, FTP or rsync. Replace the old files and leave nothing extra.
Paid hosting. Ordinary hosting or a small server costs from a few euros a month. For a server HERON puts a ready nginx config into dist/. Prices change, check with the provider.
Free hosting. GitHub Pages and Cloudflare Pages take the dist/ folder with your domain and HTTPS. GitHub Pages: up to 1 GB per site, public repositories only on a free account, not for shops. Your domain on GitHub Pages
Every update. Build and copy again: nothing happens on its own.

Full guide: ready files and where to host them →

You build the siteYour step
You check it on localhostYour step
You copy dist/ to the hosting^¹Your step
Once: domain and HTTPSYour step
The site is liveAutomatic
Next update: build and copy againYour step

Your step Automatic · 1 of 6 steps runs by itself: every update is by hand

¹ Where: shared hosting or a VPS (from about €5 a month), or free on GitHub Pages and Cloudflare Pages.

Why git is the best way to store your content

Git keeps the history of every file of the site. You don't need to learn all of git: three commands cover daily work. Publishing then follows by itself.

Every change can be undone

Each edit is saved as a step with a label such as "New prices". You see what changed in any file, and the whole site goes back to yesterday with one command.

The image build is already built in

GitHub builds the image of the site right in the repository and stores it there too. No extra accounts or registries to set up.

Send, and the image is ready

Set up once, you send your changes to git and a fresh image builds by itself. With HERON Agent it also updates on your server by itself.

HERON Agent

Correct dates for search engines

The date a page last changed is taken from the history, so the sitemap tells search engines exactly which pages to reread.

One history for you and your AI agent

The agent works on a copy, you see what changed and accept it. Nothing changes on the site without a trace.

A free backup

The whole site with every version lives on GitHub. Laptop broke? Nothing is lost: clone the repository and carry on.

How storing in git works →

Fast, findable, hard to break

A HERON site is a set of ready pages served by nginx, a small and fast web server. That one decision makes it fast, easy for search engines to read and very hard to hack. Open a card to see how each part works.

Fast

Pages are built in advance, so the server only hands over finished files. A visitor on a phone gets the page at once, without waiting for anything to be assembled.

Why: Nothing is put together while a visitor waits: no database queries, no code running on the server, no plugins loading one after another.
Images: Every photo comes in light WebP and AVIF copies of the right size for each screen. A phone never downloads the picture made for a large monitor.
Small pages: The theme loads only the styles and scripts it needs. Pictures far down the page wait until you scroll to them.
Caching: The nginx config HERON writes tells browsers to keep pictures and styles, so the second page opens even faster.
Proof: A new HERON site scores 100 for performance in Lighthouse on a phone, and its home page weighs 3 KB.

Built for search

The configurator collects everything search engines need, and the rest is built from it. You answer questions once, and every page carries correct data.

schema.org: What the site is about, who runs it, where and how to reach them: structured data on every page, from site.yaml. Search engines can show it as rich results: address, opening hours, questions and answers.
One source: The sitemap, llms.txt for AI assistants and the page markup come from the same data, so they never disagree.
Hints in every page: The top of each page file is an SEO block with a comment on every line: title up to 60 characters, description up to 155, what each field does.
Checked: The strict build stops on an empty description, a broken link or a missing translation, and names the file and the line.
Languages: Each language has its own addresses and hreflang tags, so every country sees its own version in search.

SEO and languages in detail →

Hard to break

There is nothing on the server to break into: no admin panel, no PHP, no plugins. Most hacked sites are broken through exactly these three things.

No login page: There is no password to guess and no admin address to attack: pages are edited in files on your computer.
Closed build: The build runs in a container under your user and sees only the site folder. It can't touch the rest of your computer.
Only the result goes live: The image holds the finished pages and nginx. No history, no source photos, no drafts, no HERON itself.
Drafts stay private: Any build that is not the final one tells search engines not to index it, so a test version never shows up in search.
A fixed version: The first line of site.yaml names the HERON version, so a new release never changes a live site by surprise.
Hidden files stay hidden: Addresses like /.git/ answer 404, so nothing from the folder leaks out.

Data through a module

The default build has no database, and most sites never need one. When a site needs live data, such as prices from a catalog or answers from a form, it is connected as an optional module.

How it works: The site and the database talk over a private key. A page only reads data or sends a request, such as a form.
Why it stays safe: The built container cannot be changed from outside, so there is no way to inject code into it to reach the database.
What stays the same: Pages are still ready files: the module only fills in the live parts, and the rest of the page loads as fast as before.
When you need it: A price list that changes daily, a booking form, a catalog with hundreds of items. A page about your services doesn't need it.
More: Why a site without a database is safer

The work you would otherwise do by hand

All of this is on from the first build. Open a card to see what it changes, how it looks in the files and where to tune it.

Search optimisation

sitemap.xml, robots.txt, a canonical address for every page and structured data for pages, breadcrumbs and questions. Built on every build, nothing to install.

Changes: How fast new pages are found and how they look in search results.
Sitemap: Every page with the date it last changed, so search engines read only what is new.
Canonical address: One true address per page, so two spellings of the same address never compete with each other.
Questions: A section with the anchor {#faq} becomes questions and answers that search engines understand.
Tune: The configurator fills the data; fine-tune with the seo and schema blocks of site.yaml.

SEO settings →

Translation into languages

Each language gets its own addresses, search engines see which pages are translations, and visitors get a language switch. Adding a language is a line in the settings and a folder of pages.

Changes: Each language ranks in its own country and search results.
Addresses: The main language lives at /about/, the others under their code: /ru/about/, or with a translated address such as /ru/o-nas/.
Tune: List the languages in site.yaml, then copy a page into the folder of the new language and translate it.
Links stay right: A link written once as /services/ leads to the services page in the reader's language.
Nothing forgotten: The build report lists pages that have no translation yet.

site:
  languages: [en, ru, de]

Multilingual websites →

Image processing

Put a photo in media/. HERON makes light WebP and AVIF copies in every size the theme needs and picks the right one for each screen. You never resize a picture by hand.

Changes: Speed on phones and the Core Web Vitals score that search engines use.
What you do: Drop the largest photo you have into media/ and refer to it from the page.
What HERON does: Cuts it to the widths and shapes the theme asks for and writes the code that lets the browser choose.
Only what is used: Pictures nobody links to are not processed, so the build stays fast.
Tune: Sizes come from the theme, the caption from the page.

Images and themes →

Redirects from old addresses

Real redirects from your old site and a clear «gone» answer for pages you removed. Moving a site no longer means losing its place in search.

Changes: Rankings survive a move, from WordPress too.
One page: Write the old address in the page that replaces it, under redirect_from:. Visitors and search engines land on the new page with a permanent redirect, code 301.
Removed pages: List them under gone: in site.yaml; the server answers 410, and search engines drop them quickly.
Masks: /wp/* closes every address that starts with /wp/ in one line.
Real, not a trick: Redirects go into the nginx config, not into a page that refreshes after a second.

redirect_from:
  - /old-services.html

Redirects and answer codes →

Preparation for AI assistants

llms.txt with a short description of every page and llms-full.txt with the full texts, in every language. AI assistants read your site the way you wrote it.

Changes: How chat assistants describe your company and link to you.
Where it comes from: Each line is the page's heading and description, the same ones you write for search.
Facts: Add a few lines in seo.llms_note of site.yaml: how to reach you, when you work, what you don't do.
Private stays private: Pages with noindex or not published stay out of the file.
Tune: On by default and built from your pages.

What llms.txt is → · Make one for any site →

A correct 404 for every case

A «not found» page in every language with the right answer code, 410 for removed pages, 404 for hidden files like /.git/. The server never pretends a missing page exists.

Changes: A missing page is never indexed as a copy of the home page.
For visitors: A friendly page in their language with links back to the site.
For search engines: The real code 404 or 410, so they stop asking for addresses that don't exist.
Tune: content/en/404.md and its translations, written like any other page.

Answer codes →

Start from a theme, keep your content

Starter

The theme every new site starts with. Clean and light, every page type works from the first minute.

heron new my-site

Product

HERON

A product site with a live hero, docs links and an ecosystem map. The theme of this website, light and dark.

heron theme get heron .

Medical

Clinic

Services, doctors, conditions and booking, in several languages. Built for clinics and private practice.

heron theme get clinic .

Legal and business

Firm

Practice areas, team, cases and contacts for a law or business firm. Serious type, quick contact.

heron theme get firm .

All themes

Your AI agent already knows how to work with HERON

An agent fills your pages: it writes and changes the text in content files by your request and fills the required fields. It does not touch the structure or the theme, and every build checks its work.

Claude CodeGive it a task in plain words, and it fills the pages of your site.Claude DesignHand it your mockup and the designer guide, and it builds a theme.CodexThe same rules, the same commands, the same checks on every build.Skills for any agentOne command installs the HERON skills from skills.sh.Any other agentheron docs prints the documentation for exactly your version.

the docs ship inside the image

One builder, and tools around it

HERON builds the site. The rest of the ecosystem keeps it running and tells you how it performs. Use only what you need: the Agent and the Bot are paid add-ons.

Click a block, or watch the story play

HERON CMS

The builder. It creates the folder of a site and turns its text pages, theme and settings into a finished site. Free and open source.

What it does: Pages, search markup, languages, images, sitemap, llms.txt and the nginx config, in one build.
Where it runs: On your computer, on GitHub or on your server: one Docker image or one pip package.
Try it: heron new my-site creates a site with demo pages in a minute; heron serve . shows it in your browser.
Checks itself: heron check . lists what is missing: empty descriptions, broken links, pages without translation.
Docs inside: heron docs prints the documentation for exactly the version you run.
Read more: How a site folder works

HERON Botbot

Today

Pick the right tool for the job

HERON is for business sites, blogs and docs that should be fast, easy to find and cheap to keep. Need a shop or a visual editor? WordPress does that better.

	HERON	Hugo	WordPress
Best for	Business sites, blogs, docs	Blogs, docs, large static sites	Shops, portals, sites edited in a browser
Database or PHP on the server	None	None	Required
Search settings with hints on every page	Built in	Up to the theme	Plugin
Languages and language switch	Built in	Up to the theme	Plugin
llms.txt for AI assistants	Built in	By hand	Plugin
Redirects from old addresses	Real 301 and 410	HTML page with a refresh	Plugin
Ready image of the site for a server	Yes	No	No
Guides for AI agents	In the repository and the image	Search on your own	Search on your own
Set up without code	Configurator with a hint on every field	No, config files	Admin panel
Visual page editor in the browser	No, text files	No	Yes
Online store, accounts, comments	No, not the goal	No	Yes, with plugins
Themes and plugins to choose from	A few, and growing	Hundreds of themes	Tens of thousands
Build speed on thousands of pages	Good	Fastest	No build step

marks where a tool is strong.

Guides and answers

Short pages for the questions people ask before they build a site.

New to all this? Docker, an editor, Markdown, git and a domain, explained from zero.What is a static websiteHow it differs from a dynamic one, and when you need a database.Flat-file CMSA site from text files, with no database.llms.txtThe file that tells AI assistants what your site is about.llms.txt generatorMake the file for any site in your browser.A website without codingFrom a form and text files to a live site.Portfolio websiteYour own portfolio in an evening.GitHub Pages with your domainDNS records and HTTPS, step by step.From Obsidian notes to a websiteThe same markdown files, published.Multilingual websiteAddresses, hreflang and a language switch.Project newsReleases and new features.BlogWalkthroughs, cases and moving from WordPress.

Ask, follow, contribute

GitHub

Questions, ideas and code. Contributions are welcome, from a fixed typo in the docs to a new theme.

Repository: github.com/FMSTM/HERON
Start here: README and AGENTS.md explain the project in a few minutes.; Found a problem? Open an issue with the command you ran and the message you got; the build report already names the file and the line.; Want to help? Docs, translations and themes are the easiest place to start.

Telegram channel

Releases, new themes and notes on building sites with AI agents.

What to expect: A short post per release and practical tips.
How often: When there is something worth reading, not every day.
Also there: New themes with demo links and examples of sites built on HERON.

Support bot

Ask a question or suggest a feature right in Telegram.

How it answers: From the documentation first, and a person when the docs are not enough.
What to send: What you wanted to do, the command and the message you got.
Ideas welcome: Suggestions go straight to the list the next releases are planned from.

Support the project

Donations keep HERON and the free themes moving.

Where it goes: Development time, test servers and new themes.
Other ways to help: A star on GitHub, a link from your site, a word to a friend who needs a site.
Everything stays free: HERON itself remains open source under AGPL-3.0.

Your site is one command away

Create the folder, fill in the configurator, open the site in your browser.

Docker

Get started Star on GitHub