Why I keep drafts and canonical posts separate

I don’t write posts into the file that ends up published. The rough version lives in a notes/ folder, and the canonical post only shows up once I’m happy with the thing. It took me a while to settle into that shape, and I keep it because editing one file from first idea to final version turned out to be worse for me than moving the work between two.

This is a setup note, not a theory. It’s what my blog folder looks like day to day.

What lives where

The split is simple. There’s a working lane and a canonical lane, and each file has exactly one job.

In notes/<slug>/ I keep a brief, one or more draft versions, and whatever review notes came back on them. It’s fine for this folder to be untidy. Draft filenames get suffixes, there are half-written sections, there are lines I haven’t decided about. Nothing in here is load-bearing for the site.

In src/content/tech/<slug>.md there’s one file. It has frontmatter, a title, a date, and the finished post. No alternative versions, no review comments, no scratch. When I build the site, this is what gets rendered.

The separation means I can be noisy in one place and quiet in the other.

Why not draft in the canonical file

The obvious move is to write straight into src/content/tech/<slug>.md with draft: true and flip it to false when done. I tried that for a while. A few things got in my way.

The first is that any file the build system knows about starts to feel load-bearing. Even with draft: true, once it’s in the content tree I’m editing it with one eye on how it’ll render and one eye on whether the slug is right. That’s not the mode I want when the post is still deciding what it’s about. I want to be allowed to write a bad paragraph without feeling like I’ve polluted the canonical tree.

The second is versions. Drafts go through shapes. I’ll often have a v1 that’s too long, a v2 that’s cleaner but missing a section, and a v3 that merges them. In a single canonical file that history is gone by the time I’m done. In notes/ I keep the intermediates until the post is out, which means I can lift a paragraph back from v1 if v3 wandered too far.

The third is review. I’ll come back to that one.

Review notes belong next to the draft

When a draft is close enough, I hand it to a stronger model with the brief and ask for a review. The output is a file. It sits next to the draft as review.md or similar. Then I read it, decide what to apply, and edit the draft.

I used to do this in a chat window. The problems piled up quickly. The review scrolled off. I’d apply half of it, forget the other half, and not realise until I was looking at the published post a week later wondering why a suggestion I agreed with hadn’t made it in. Worse, the thinking about which suggestions to take and which to drop happened in my head and left no trace.

Writing the review as a file, in the same folder as the draft, fixes both. I can see what was suggested. I can see what I decided. If I disagree with a note I can leave a line saying so, and that sits on disk too.

The diagram is boring on purpose. Each arrow is a file being read or a file being written. Nothing important lives in a chat transcript.

Being wrong first, tidy later

The real thing the split does for me is give the draft permission to be wrong. When the canonical file is the only file, every sentence I write has to survive into the final post or be deleted. That’s a lot of pressure for a first pass, and it makes me cautious in a way that produces worse writing.

When the draft lives in notes/, I’m allowed to overwrite it. I can write a version that’s too long and trim it. I can try a structure, decide it doesn’t work, and try another one. None of that shows up in the canonical tree, and none of it is on the site.

The canonical file, in return, stays boring. It has one version. It doesn’t accumulate comments or alternatives. When I read it a year later I’m reading exactly what got published, not what I considered publishing.

Remembering what was final

That last part matters more than I expected. A year in, I can’t always remember which version of a post actually went out. If every draft and alternative still lives in the canonical file as crossed-out sections or commented blocks, I have to read carefully to find the shipped text. If the canonical file only ever contained the shipped text, I can just read it.

The drafts are still around if I want them. They’re in notes/. But they don’t get in the way.

This also helps when I want to write a follow-up. I can open the old brief and the old review notes to see what I was trying to do at the time, without that context bleeding into the finished post.

Where it costs

It’s not free. There’s a small moment when I copy the final draft into src/content/tech/ and have to make sure the frontmatter is right, the slug matches, and I haven’t accidentally left a v2 marker in a heading. I’ve shipped a post with a stray TODO in it at least once.

There’s also duplication. The final paragraph of draft-v2.md and the final paragraph of the canonical file are the same text for a while. If I notice a typo after publishing, I have to decide whether to fix it in both or just the canonical one. I fix the canonical one and leave the draft alone, but it’s a small friction.

And the notes/ folder gets noisy over time. Old briefs, old drafts, old reviews. I prune occasionally but I’m not disciplined about it. Sometimes I go looking for an old draft and can’t find it because it’s three folders deep under a slug I don’t remember.

Where it sits now

Briefs, drafts, and review notes in notes/<slug>/. Canonical posts in src/content/tech/<slug>.md, one file each, kept boring. The copy step between them is the bit where I decide the post is done.

It works for me because the two files have two different jobs, and keeping them in two different places is the thing that lets each one do its job properly.