The Problem With Reaching For a CMS

For twenty years the default answer to "how do I run a content site" has been "install WordPress" or similar. For sites with multiple editors, a non-technical client, or a workflow that involves a review queue — that answer is still usually right. But a lot of sites don't have any of those requirements.

A personal portfolio doesn't need a database. A small documentation site doesn't need a plugin ecosystem. A developer blog doesn't need a WYSIWYG editor. For these cases, pulling in a full CMS is adding complexity to avoid a problem you don't have.

What Flat-File Actually Means

"Flat-file CMS" is an umbrella term that covers a range of approaches. At the minimal end — which is what this site uses — it means:

• Content lives in YAML and Markdown files checked into (or alongside) the repository
• A thin backend reads those files at request time and serves them as JSON
• The frontend consumes that JSON like any other API

There is no database, no admin UI, no authentication layer for content editing, and no plugin system.

What You Edit

For this setup, editing content means editing a YAML file in a text editor. For a developer, that's fine. For anyone else, it's a dealbreaker — which is a useful filter.

A typical content file looks like this:

title: On Flat-File CMS
date: 2025-06-01
summary: Why a YAML + Markdown setup is often the right call.

Long-form body content goes in a Markdown sibling file with the same slug. The backend reads both and merges them into a single response.

What You Gain

Zero Infrastructure

No database container. No migration scripts. No backup strategy for a database. No version upgrades that break the schema. The content is files — you back them up however you back up files.

Content in Version Control

YAML and Markdown can live in git. That gives you a full history of every content change, the ability to roll back to any previous state, and a diff-friendly format for reviewing changes. A WordPress database export is not diff-friendly.

Branching

Because content is files, you can branch content changes the same way you branch code changes. Drafts are branches. Feature flags for content are trivially possible.

Lower Attack Surface

A CMS is a piece of software with a login screen, an admin UI, and a plugin ecosystem — all of which need to stay patched or they become the way a site gets compromised. A flat-file setup with a backend that only exposes read-only API routes has none of that: no admin login to brute-force, no plugin vulnerabilities, nothing to patch just to stand still.

No Theming Constraints

There's no CMS template system to work within or around — no theme layer, no template overrides, no fighting a component library's markup to get a custom layout. The frontend owns the markup and CSS outright, so creative or unconventional visual design is just as easy to build as a stock layout would be.

Portability

The content files are not tied to any specific backend or frontend. If you replace the Slim PHP API with a Node.js server next year, the YAML files don't change. If you replace the Vue frontend with something else, same story.

What You Give Up

No Querying

A database lets you run arbitrary queries: give me all articles tagged "PHP" sorted by date, give me the three most recent posts, give me everything published in 2024. Flat files can't do that efficiently at scale.

For a site with a handful of content types and tens or hundreds of items, manifest files (ordered YAML lists) are a workable substitute. For anything larger, you'll eventually hit a wall and wish you had a database.

No Transactions

If a content update involves multiple files (say, updating a manifest and the item it references), there's no transaction to keep them consistent. A half-finished update leaves the site in an inconsistent state. In practice this matters less than it sounds — the window is small and it's a personal site — but it's worth being honest about.

No Editor UI

Worth repeating: if the people editing content are not comfortable in a text editor and a terminal, this approach does not work for them. It also assumes you're comfortable on the other side of the stack — SSHing into a server, running an rsync deploy, and knowing what breaks the site if a YAML file is malformed. This isn't a setup for someone who just wants to log in and type into a form.

No Browsable Editing

A CMS admin lets you click through the live site and edit what you see. Flat files don't work that way — there's a layer of indirection between what's on the page and which file produced it. In practice that means memorizing (or keeping a cheat sheet on) how content is organized: which directory holds which type, how manifests reference slugs, which YAML field maps to which field on screen. It's a different mental model from "click edit, see form."

When It's the Right Call

My rule of thumb: if the site has one editor (you), fewer than a few hundred content items per type, and no requirement for real-time content updates or complex querying, flat-file is worth considering. The simplicity dividend is real.

For everything else — multiple editors, non-technical clients, complex taxonomies, e-commerce, membership sites — reach for a real CMS. The infrastructure complexity pays for itself.