One YAML file, a whole blog: how this site builds itself

1. One article, one file

On this site, an ordinary article lives in one YAML file. Think of it as a structured document: a title, a short description, a date and the sections of your story. You can add an introduction, a closing invitation, sources and visuals when they help.

Place that file in the articles folder and the site discovers it. Its filename becomes the article's web address. The title joins the home page and Articles menu, and the section headings create the table of contents. There is no separate page to assemble for each post.

That matters most after the first few articles. A custom design is enjoyable once; repeating the same setup every time is less so. Here, the publication remembers its structure so I can concentrate on the next story.

A finished draft should feel close to a finished page.

2. The small chores take care of themselves

The article's details travel with it. Its title and description appear wherever the site needs them: on the listing, in search and sharing information, and in the RSS feed. The sitemap updates too, and the article gets its own discussion thread.

Before building the page, the site checks the document for common mistakes, such as missing information or an image that does not exist. It then creates a complete, readable page, with the words already present when a reader opens it.

Automatic discovery does not mean instant public release. Changes appear in the local preview while I write; publishing still needs a build and deployment. Those release steps can run automatically when the hosting is connected to the repository.

From the exploration

Write once. Let the site do the rest.

Open full-size diagram

3. A recognizable publication, without identical articles

Every article shares the same reading experience: typography, spacing, headings, navigation, figure frames and closing cards. These choices live in the site's design, so I do not make them again while writing.

Within that design, each article chooses what it needs. A comparison can use a table. An argument can use a pull quote. A process can use a diagram. Source links can stay visible or fold into a small reading list. The site puts each feature in a consistent place and gives it the same treatment across articles.

Improvements spread naturally. Refine the table style or make captions easier to read, and every article using that feature benefits on the next build. A new visual feature can be designed once and made available to future posts, rather than becoming a one-off page that nobody wants to maintain.

Choose the material for each article. Let the publication remember how it should look.

4. Bring the diagrams, leave the clutter

Mermaid lets me describe a diagram in text: the steps in a process, the messages in a conversation, or the connections in a system. It is particularly useful when a picture can replace several paragraphs of explanation.

This site turns those descriptions into images using a shared parchment, copper and gold palette. Each diagram gets the same frame, caption, alternative text and full-size link. Readers receive a finished image, without having to run a diagramming tool in their browser.

There are also reusable diagrams and tables that an article can describe directly. A plain essay can stay a single file; a custom Mermaid illustration adds its source and finished image. The extra effort goes into explaining the idea, while the site handles its presentation.

Graphs should earn their space. Use a table when exact values matter, a flowchart when order matters, and a numerical chart when a pattern matters. A consistent visual style helps, but a useful caption and sound data do more work than decoration.

5. Keep the everyday routine small

My routine is write, preview, check and publish. The preview shows the article in the same design as its neighbors. Checks catch broken structure and help confirm that the finished page works. The final release puts the update online.

Discussion is part of that shared experience too. An empty thread stays discreet, with a small “Leave a comment” control. Readers can agree, push back, ask a question or add context; new comments wait for review by default.

The initial setup still takes work: your identity, design, domain and hosting need decisions, and a custom site needs maintenance. The reward is that ordinary publishing no longer asks you to revisit all those decisions. Automation handles the repetition; the argument, editing and fact-checking remain mine.

6. You do not have to build it this way

This approach suits me because I enjoy shaping the reading experience and want reusable visual features. Another blogger may value an editor, newsletter delivery or less responsibility for the publishing system. Those are good reasons to choose a different starting point.

Astro, Eleventy and Hugo offer established paths for turning content files into a custom site. I would choose around the experience I want while writing, rather than the longest feature list.