My Blog Is a Folder of Markdown a Robot Writes

For a while every tutorial on this site was a hand-built page. Real HTML, real care, and a real reason not to write the next one. The writing took an hour. The plumbing took another: the page file, the entry in the feed, the tags, the RSS. By the time it was live I didn’t want to start again.

So I changed the shape. The post is now a plain markdown file in a folder. Everything else reads from it.

One file in, four surfaces out

The trick is to have a single place the rest of the site reads from. Drop a markdown file in src/content/articles/, and the index feed, the curriculum rail, the tag pages, and the RSS feed all pick it up. I write none of that wiring per post. It happens because the file exists.

That’s the whole idea: the file is the source of truth, and every surface is a view over it. Add the file, get the page and the four places that link to it, for free.

The body is markdown, the chrome is shared

A markdown file can’t describe a page layout, and it shouldn’t have to. The header, the back link, the email box at the bottom, the styling: that lives in one template the article renders into. The file carries the words and a little metadata at the top. The template carries the look.

This is the part that took me longest to accept. I wanted control over every post. What I actually wanted was for every post to look right without me deciding again. Shared chrome gives you that, and it means the day I change the design, every post changes with it.

Publishing is one yes

Here’s the move that made it stick. The draft doesn’t appear out of nowhere. Something writes it from the work I already did, and it lands somewhere I review behind a login. I read it. If it’s good, I publish, and publishing is a single commit of that markdown file to the repo. The site rebuilds and it’s live.

No copy-paste, no second editor, no “I’ll post it later” that means never. The expensive step got cheap, so the posts actually go out.

The point

If you write more than you publish, the problem usually isn’t discipline. It’s that publishing costs too much each time. Make the post a file, let one place read all your files, share the chrome, and reduce the final step to a yes. Then the only thing left is the writing, which was the part you wanted to do anyway.