An Article Is a File
By John Hardy
I treat each article as a single Markdown file inside its own folder because I want the archive to stay inspectable and durable. A reader can open the file and see the full text in a stable shape, which keeps the record legible years later. You can also clone the archive and read it in plain text when the build changes.
Each entry lives in its own folder. The folder path carries the date and slug. The file carries the writing, so URLs stay aligned with edits.
Open article.md in any entry and you always see the same two-section structure. A YAML block sits at the top and the Markdown body follows, which keeps the writing distinct from the data surface. I write the body for readers and use frontmatter so the build can work without reading it.
---
title: "The Shape of the Archive"
summary: "How this blog organises itself on disk instead of inside a database. The path does the work."
series: genesis
tags: [tooling, publishing]
status: published
thumbnail: hero.jpg
---
Here is where the writing begins…
Everything above the divider is frontmatter for indexing, and everything below it carries the published text. The build reads the YAML block to assemble lists for series and tags, then renders the body as the article page. Titles and summaries let index pages render without scraping prose, and the series value places the article inside a narrative. Tags attach the entry to topics and status controls visibility, so lists stay mechanical and templates stay focused on structure.
That pairing is the reason each permalink stays stable and reviewable even when the build changes.
Some values appear in both places because each surface has a job. Titles and summaries belong in lists, while the article uses its own headline. A summary can stay out of the body so indexes stay concise, which keeps index pages tight while the article stays expansive. This separation keeps the body’s voice intact even when I refine index rules.
From a tooling point of view this keeps articles easy to work with. The file reads cleanly in a text editor. The metadata parses cleanly in small scripts. Git diffs stay tight enough to scan in seconds.
For readers this means the permalink remains stable and the record stays open to inspection. For me it means a predictable build and a file I can review years later. That durability is the payoff of treating the file system as the source.
The Article Body
By John Hardy
Frontmatter defines an article for the build, but the body carries the meaning for readers. It is the section a reader actually meets, so I treat it as the record that must survive every build. Everything below the YAML block exists to be read, and that focus drives the format and the discipline. The body holds the text and keeps links and code beside the media, so the file stays readable before and after the build touches it.
Markdown keeps the text close to plain language. Paragraphs and headings read the same in a terminal or a diff viewer, so the file stays legible wherever it travels. That consistency lets me review drafts without leaving the file. That stability is why I keep the body in Markdown even as the rest of the system shifts. I begin the body with the title and sometimes a byline so the file stands on its own. Dates and tags sit in metadata blocks outside the prose. Sections use normal Markdown headings, which keeps the body free of page and layout syntax.
Layout lives in templates and the body stays focused on narrative structure. I add section breaks to serve the argument, and the template controls how headings appear on screen. Links point to published URLs and stay explicit in the prose, which keeps filesystem paths out of the body. Code blocks use fenced Markdown and avoid inline tooling because the code exists to be read. Syntax highlighting can happen in the browser when it helps.
Images and other assets live beside the article inside an assets/ folder, so each entry carries its own attachments. There is no shared media pool, which keeps the archive legible on disk and makes a clone complete by default. It also keeps attribution and context close to the writing that references the files.
content/blog/2026/01/11/02-the-article-body/
article.md
assets/
diagram.webp
hero.jpg
The Markdown references assets by relative path so the entry stays self-contained when the folder moves. The build copies the assets/ directory into the public tree and keeps the same structure in place, which keeps images working in indexes and on their own page. The source stays clean because the paths remain visible and easy to review.
The body avoids embedding logic and leaves lazy loading and presentation to templates, while the Markdown stays presentation-agnostic and media framing stays in the layout layer. That boundary keeps the writing stable, so I can edit a paragraph or add a code block without worrying about the rest of the system. The body remains a record, not a rendering script.
These posts describe the system that publishes them, and they do so in the same format as every other article. That keeps the documentation inside the pipeline, and the body serves as evidence of the approach. When the build changes, the archive stays reliable. If an idea cannot live inside Markdown with links and headings, I treat that as a design problem and fix the system until it can. The body is my promise to readers: it stays readable even if the build disappears.
