I designed this format for me, but Claude likes it better.

When I rebuilt this site, the first thing I wrote wasn’t code. It was a spec for how a post should be stored on disk. Before there was a home page, an editor or a blog design, there was a document describing folders and files.

Every post is a folder with a date and a slug in its name. Inside is a hero photo, an optional folder of images, and one file, index.md. The top of that file is a short block of YAML:

---
title: "I designed this format for me. Claude likes it better."
date: 2026-10-04T18:08:11-07:00
dek: "Every post on this site is a plain text file with a little YAML on top."
heroAlt: "A red manual typewriter with cream keys"
draft: true
---

Below that is the post itself, in Markdown. There’s no database, no relational tables. The site’s colors aren’t even stored; they get pulled out of the hero photo every time the site builds.

My Reasons

I can edit it with anything. I love a good text editor, and a post is just a text file. I can open it in BBEdit, in the editor I built for this site, or in whatever app is handy on my phone. Nothing about the format is special or fussy.

Git just works. Every post lives in a git repository. History is included. Rollback is free. Publishing is just a push away. Backing up the whole blog is cloning one repository.

Astro barely has to try. A static site generator wants files, and these are files. Astro reads the folder, parses the YAML, validates it against a schema, renders the Markdown and writes HTML. If something’s wrong, the build fails and tells me exactly which file is broken.

All of that was on purpose, but it’s not very interesting. People have been building blogs out of Markdown files for well over a decade. I’m late to this particular party.

The reason I didn’t have

The thing I thought about least when I designed the schema has turned out to matter most: Claude can read and write these files without any help.

After thinking about it for a little bit, I’ve decided this is a pretty big deal. Think about what it takes for an AI to add a post to a more traditional system:

It could drive the admin interface: log in, find the right screen, fill in the right fields, hope the rich text editor doesn’t screw anything up, and click Save. That’s slow, brittle and expensive, and it means teaching a model a UI that exists to make sense to humans. My editor here is custom, built just for me. Nobody has ever written documentation for it, and nobody ever will.

Or it could skip the UI and write to the database directly. I’ve spent most of my career on a CMS, so I know how that goes. Concrete ships with roughly one million database tables, so getting content into those in a way that makes sense and renders well is not easy. Get one row wrong and the page breaks in a way that might not show up until someone visits it. No sane person hands that job to anything without a lot of guardrails.

Compare that to this site. To write a post, Claude makes a folder and writes a text file. It already knows Markdown. It already knows YAML. When it’s done, it runs the same build check I do. If the check fails, the error points at a line in a file, and Claude fixes it the same way I would.

Now what?!

I didn’t set out to build a blog that an AI could work on, but that’s what I lucked into.

Claude has a written set of instructions in the repository for drafting a post: read the format spec, read a couple of my posts for voice, find a hero photo, write the file, run the check, leave it as a draft. The first rough draft of this post came out of exactly that process. (What you’re reading now has been through my hands, I promise.) There’s a similar set for thoughts, the little untitled posts on this site. When I dictate one to Siri on my phone, it goes to my Linux box at home, and Claude turns it into a file.

Obviously, storing your site’s data files in a plain text format isn’t some panacea. If I had a dozen authors with different permissions, I’d want a real CMS. But this site has one author, a git repository, and an assistant that reads plain text better than it reads my menus. I picked the format for BBEdit, git and Astro. That it suits Claude even better was luck, not planning.