Why markdown files over a CMS

Part of “Why this over that”: short posts about technology choices I’ve actually made, with the reversal conditions stated honestly.

The site you’re reading is a folder of markdown files, rendered to static HTML at build time. No CMS, no admin panel, no database, no editor with a toolbar. When I want to publish, I write a text file, and this post is the case for that being a feature list rather than an absence of one.

The case, in five properties

Writing happens where I already live. A post is a file in the same editor, with the same tools, as everything else I make. There’s no second interface to log into, and no context switch between “writing code” and “writing writing.” Friction at the moment of starting is the number-one killer of personal blogs (I have a graveyard’s worth of evidence), and a text file is the lowest-friction start there is.

Git is a better CMS than the CMS. Version history, drafts as branches, diffs on edits, blame on every sentence: the CMS features I’d actually use come free from the tool I already trust with my code. My words get the same infrastructure as my software, because they’re in the same kind of repository.

The failure surface is nearly zero. A static site has no admin login to breach and no plugin treadmill to fall behind on. (There is a small database behind the likes and comments now, but it sits beside the site rather than under it: if it fell over entirely, every word here would still render.) The blog cannot have an incident in any meaningful sense; the worst case is a failed build, which fails before deploy, visibly, on my machine. For the never-operate-what-you-don’t-have-to school, a personal site is the purest application of the doctrine.

Portability is the exit everyone claims and files actually deliver. Every platform promises export. What that export yields is a tangle of HTML in someone else’s schema. My posts are already the interchange format: plain text with front-matter, readable by every tool that will exist for the rest of my life. The blog could move from Astro to anything over a weekend without touching a single post.

Constraints keep it honest. No plugins means no analytics creep, no popups, no seventeen embeds slowing the page to a crawl. The site stays fast and quiet because there’s no mechanism for it to become anything else.

The honest reversals

• Non-technical authors. The moment someone who doesn’t live in a text editor needs to publish, the calculus flips completely. “Just edit the file and push” is a wall, not a workflow. Teams, marketing sites, multi-author publications: get a CMS, ideally a headless one so the rendering stays yours.
• Editorial workflow. Scheduling, review queues, roles and approvals: git can cosplay all of these, but a CMS does them natively and legibly for non-engineers.
• Content that isn’t documents. Once “posts” become structured records with relations (products, listings, recipes with metadata that drives features), you want a database with a schema, not front-matter straining under the load.

The pattern underneath, one last time: the tool serving one person can shed every layer that exists to serve many. This series’ SQLite post is the same argument wearing a database costume. Count the authors, like you count the computers.

Also in this series: Why SQLite over Postgres, Why SSE over WebSockets, and Why Go for the service, Rust for the tool.