The One-Command Press

By Ali AlQattan. How a Breakdown gets published on this site.

TL;DR

Publishing here is one command, one markdown file, and a push. Run node scripts/new-breakdown.mjs <slug>, write the article, run the tests and the build, push to main — the deploy carries it live. The registry tests refuse a hollow page: a missing file, route, or title goes red instead of publishing silence.

1. One command sets the press

Everything a Breakdown needs lives in four places. The markdown goes in src/sheets/articles/<slug>.md. The registry record in src/sheets/breakdowns.json carries the title, dek, date, tags and figure captions, and everything else reads it: the index, the route table, the crawler page in services/seo.ts, the RSS feed and the share card. The art is a holographic foil sticker for the hero and, when a section earns one, a wide foil plate beside it. Both are generated in the site's style and cut out to transparent WebP in public/art.

The command takes the slug plus the human parts: --title, --dek, --tags, and optionally --date (it defaults to today). Slugs are letters, digits, _ and -; anything else, or a slug the registry already names, dies loudly on the spot.

2. The markdown is the whole article

The markdown file is the source of truth; the owner press only edits that file. It renders through the same ink-body print as every sheet: ruled section heads, hairline tables, mono code blocks, underlined links, and a blockquote set as a pull quote. Write around 2,000 words, prefer tables over long prose, link real sources.

The markdown file is the whole article. Everything else only edits it.

Section figures are token lines, each on its own line with blank lines around it:

[[spot:chain]]

A token claims the prose that follows it. On a wide screen its plate sits in the margin beside that section; on a phone it runs full width above it. New articles start with no spots and the hero carries the page alone. When a section earns a figure, its plate is generated, registered with a caption, and tokened into place, which is how the two plates in this article got here. Unknown tokens never print: the build-time tests pin every token to a real image.

3. The tests refuse a hollow page

This is the part that makes it a press and not a folder of drafts. tests/breakdowns.test.ts asserts every registry entry ships its markdown, its hero sticker, and every spot plate it names; that every route answers with a 200; and that every article is advertised to crawlers with a matching title. The build itself inlines the rendered markdown into the static HTML, so a reader without JavaScript gets the article — and a PAGES entry without its markdown file fails the build instead of publishing an empty shell.

So the publishing loop is short and honest: write, npm test, npm run build, commit, push. Anything you forgot stops you before the public ever sees it. That is the entire CMS — a script that sets the type, and tests that refuse to print a blank sheet.