HTMLy

Last reviewed Sep 13, 2026 · 768 words

content/aidan/blog/homelab/post/2026-09-01-08-15-00_docker,backup_nightly-restic-runs.md

That path is an entire HTMLy post: the author, the category, the publish timestamp, the tags, and the slug are all in the filename, and the body is Markdown. There is no database, no migration step, and no export format to worry about, because the export format is the folder. Backing up a 10-year blog is rsync -a content/ backup/, and restoring it is the same command reversed. If that is the property you want from a blog engine, HTMLy delivers it with fewer moving parts than anything else in PHP.

Flat-file means the filesystem is the schema

Posts live under content/{user}/blog/{category}/post/, with drafts in a sibling draft/ directory and static pages under content/static/. HTMLy builds an index cache from those filenames on first request and rebuilds it when files change, which is why listing 2,000 posts is fast on shared hosting with 128 MB of PHP memory. Themes are PHP templates in themes/, and the site config is a small config.ini.

The consequence people miss: you can write posts without ever opening the admin panel. Drop a correctly named file into the folder over SFTP or from a git checkout, and it is live. Several people run HTMLy with a git post-receive hook and never log in.

Install is a copy and a form

Requirements are PHP 7.4 or newer (8.x is fine) with the usual mbstring and json extensions, and a web server that rewrites to index.php. Apache works out of the box with the shipped .htaccess; nginx needs a try_files $uri /index.php?$args; block. Copy the release into the document root, open the site, and the installer asks for a site name, an admin username, and a password, then writes config.ini. That is the whole install; 5 minutes is generous.

Docker has no official image, so the pattern is the php:8-apache image with the HTMLy directory mounted at /var/www/html and content/ on a persistent volume. Keep content/ writable by the PHP user and everything else read-only, since the admin panel writes only there.

Multi-user roles, and where the ceiling is

HTMLy supports admin, editor, and contributor roles, so a two-person blog or a club newsletter works: contributors submit drafts, editors publish. It ships a handful of themes, RSS and JSON feeds, sitemap generation, a search page, a related-posts block, and comment embedding via third-party services rather than a native comment store. Markdown is the only content format, with a rich toolbar in the editor.

The ceiling is the ecosystem. There is no plugin marketplace worth the name, so features arrive when the single maintainer adds them, and the project sits around 1,400 stars after 12 years. E-commerce, membership, forms, and complex layouts are out of scope. If you need one of those, this is the wrong tool and no amount of PHP will fix it.

Against the neighbours

WordPress does everything, needs MySQL, needs updates weekly, and needs a security mindset that a flat-file blog does not. Grav is the bigger flat-file PHP project with a real plugin ecosystem and a more capable page hierarchy, at the cost of more configuration and about twice the learning curve; it is the safer pick if you expect the site to grow beyond a blog. Bludit is HTMLy's closest sibling: also flat-file, also PHP, slightly larger community, JSON storage instead of filename-encoded metadata. And if you do not need a web editor at all, Hugo generates static HTML from the same kind of Markdown and removes PHP from the server entirely. The whole blogging category splits on that one question: do you need to write from a browser on someone else's machine, or not.

What I'd do

Personal blog, one or two authors, you want to write from a phone occasionally, and you never want to think about a database again: HTMLy on any PHP host, content/ in a nightly rsync, admin panel behind HTTPS, done. If you already keep the posts in git and only publish from a laptop, skip HTMLy and use Hugo, because a static site has no admin login to protect. If the site might one day need a shop or a members area, start on Grav so the migration never happens. HTMLy's job is the small, durable blog, and it does that job with a folder.