Pages in files, no database

Flat-file CMS

A flat-file CMS is a content management system that keeps pages in ordinary files, usually Markdown text, instead of a database. You edit a file, and the site changes. There is no database to install, back up or update.

HERON is a flat-file CMS of the build kind: it turns a folder of Markdown files into ready pages ahead of time, so the server only hands out files. Below: how flat-file systems work, when they fit, and what a HERON site folder looks like.

Database CMS and flat-file CMS

	CMS with a database	Flat-file CMS
Where pages live	Rows in a database	Text files in a folder
What the server needs	PHP or another language, a database, an admin panel	Files only, or files and PHP for some systems
Backup	Database dump plus files	Copy the folder
History of changes	Plugins, if any	Git keeps every version of every page
Moving to another host	Export, import, fix paths	Copy the folder
What can break	Plugins, updates, database, admin login	Very little: there is nothing running

Two kinds of flat-file CMS

Reads files on every visit

The server runs a program, usually written in PHP, that opens the Markdown file and builds the page each time someone visits. Grav and Kirby work this way.

Plus: Edit a file on the server, and the change is live at once, without any build step.
Many tools have an admin panel: You can edit pages in a browser, which some owners like.
Minus: the server works on every visit: Each page view runs code, so a cheap hosting slows down when traffic grows.
Minus: you look after PHP: PHP versions, plugins and the admin panel need updates, and an outdated one is a way in for attackers.
Good for: People who want to edit right on the server and are ready to keep it updated.

Builds pages ahead of time

A program builds every page once, when you publish. The server receives finished HTML files and just sends them, the same way it sends a picture.

Plus: nothing to hack: No program runs on the server, so there is no login form, no plugin and no database to break into.
Plus: speed: A finished page opens as fast as the server can send a file, which is why such sites score high on phones.
Plus: cheap hosting: Ready files can live on free GitHub Pages or Cloudflare Pages, or on the smallest server.
Minus: A change appears after the next build. With automatic publishing through git that is usually under a minute.
Good for: Business sites, blogs, portfolios and documentation: pages that change a few times a week, not every second.

Where HERON fits

HERON builds pages ahead of time. On top of that it adds what a business site needs, without plugins, and checks your pages before they go live.

Search: Sitemap, canonical addresses, schema.org markup, hreflang for languages. All of it comes from site.yaml and the pages themselves.
AI assistants: llms.txt and llms-full.txt on every build, with the same titles and descriptions search engines see.
Moves: Real 301 and 410 redirects for nginx from redirect_from: and gone:, so an old site keeps its positions.
Checks: The strict build stops on an empty description or a broken link, with the file and line.
Data when you need it: A database is not in the default build. It connects as an optional module over a private key; the page only reads data or sends requests.

How a HERON build works →

What a site folder holds

Everything about a HERON site is in one folder, so it can live in git.

File or folder	What it holds
`site.yaml`	The only settings file: domain, languages, menu, search and AI settings
`content/`	Pages in Markdown, one folder per language, one file per page. The path of the file is the address of the page
`media/`	Photos and images. HERON makes WebP and AVIF in every size it needs
`data/`	Lists and tables the theme shows: team, prices, partners
`theme/`	The look of the site: templates and styles

How you work with a flat-file site

You never start from an empty folder. HERON creates the structure, and from then on the work is copying and filling files.

1
Create the structure

heron new my-site -y takes the latest HERON image, and the image makes the folder: site.yaml, content/ with demo pages, media/, data/ and a theme.
2
Look at a page

Open the home page file of your site in any editor and the same page in the preview at localhost:8000. You see which part of the file becomes which block of the site.
3
Copy a file for a new page

Save any page of the theme demo as services.md next to it, or let HERON make a blank one with every section of its type. The file name becomes the address: /services/.
4
Fill it in

Change the settings block on top (title, heading, description) and the sections below, yourself or with an AI agent.
5
Build and check

The next build turns the new file into an HTML page, adds it to its section, the sitemap and llms.txt, and warns if something is missing.
6

Pages and content in detail
7

How a site folder works

What about a database?

By default a HERON site has no database: content, settings and lists live in files, and that is enough for most business sites, blogs and docs.

When a site needs live data, such as a booking calendar, stock levels or requests from forms, you connect a database through an optional module. It is not part of the default build, so a site that does not need it carries nothing extra.

Private key

The site and the database talk over a private key named in site.yaml. The page only reads data or sends a request; it cannot change the database structure.

Nothing to inject

The built container holds only ready pages and nginx. There is no program on the server that an attacker could feed code to in order to reach the database.

Parts of a page update without a reload

The rest of the page stays a ready file, so it opens as fast as before.

How the database module works →

Start a flat-file site

One command creates the folder with a starter theme and demo pages.

docker run --rm -it -v "$PWD":/site -w /site --user $(id -u):$(id -g) ghcr.io/fmstm/heron:prod new my-site

Questions

Is a flat-file CMS good for a business site?

Yes, for sites that mostly publish information: services, prices, articles, contacts. For a shop with a cart or user accounts, choose a system built for that.

Can several people edit the site?

Yes. With git, each person works on their copy and changes are merged, with the full history of who changed what.

Is there an admin panel?

No admin panel on the server. Settings are filled in through the configurator questionnaire, pages are edited in any text editor, or by an AI agent.

How fast is it?

A new HERON site scores 100 for performance in Lighthouse on mobile, with a 3 KB home page. A site of 1004 pages in two languages builds in 3.3 seconds.

Is it free?

Yes. HERON is open source under AGPL-3.0, and static files can be hosted for free.