What a build writes down

Since 1.6 the build keeps a record of what went into each page it wrote -- the post, the posts around it, the labels, the numbers a page counts. On the next build a page whose record has not moved is not rendered at all. Not rendered and then found identical: not rendered. The summary at the end says how many pages were left alone, the first number to look at when a build is slow.

The record holds only while the engine that wrote it is the same engine, so it hangs off a fingerprint of what the engine is made of -- the files under templates/, lib/, build/, locales/ and config/, hashed by contents rather than by timestamp. Change any of it and the record is discarded entire, because any of it can change every page.

Why the colour cost the archive

Until 1.7 that list also had assets/ on it, and assets/ is where the stylesheets live.

A page does not contain its stylesheet. It carries a <link> to one, and there is no ?v= on that link -- a version baked into the URL would make every page differ on every CSS edit, the same problem wearing a different coat. So the bytes of a rendered page cannot move when site.css moves. The fingerprint was covering a file no page has ever held.

Measured in a copy of the engine, on a test site of 270 posts: a rebuild that changes nothing skips all 378 pages the cache is asked about, and adding a rule to site.css still skips 378. Put assets back into the fingerprint -- the 1.6 behaviour -- and the same edit skips none.

Nothing is given up. Files under assets/ are compared with their published copies on every build, by a path that never consulted this record. The edit reaches the site as it always did, and now costs that one file and nothing else.

What is still fingerprinted, and what that costs

config/ stayed on the list, and the palette is one reason it had to.

The colours in config/site.yml are not read out of a stylesheet. They generate one -- assets/css/colors.css is written by the build, not copied from the tree -- and one of them reaches the pages a second way: the light and dark theme-color in the head of every page the layout renders is the palette's background. Change bg and every one of those pages really is different. Rebuilding them is the record being right.

Change accent and no page moves. It lives only in the generated stylesheet, and the site is rebuilt all the same: the fingerprint is taken over whole trees rather than the keys inside them, so config/site.yml moving throws config/ away. On the same test site that edit skipped nothing and rendered all 378. It is the cost this release took off assets/, kept on purpose in a smaller place -- a tree is a coarse thing to hash, and coarse errs towards work. A tree belongs in the fingerprint when a page can hold its contents; linking is not holding.

When the record is not believed

• The first build after an upgrade. This release changed lib/build_cache.rb, and lib/ is in the fingerprint, so the first build on 1.7 renders everything. An engine that worked out which pages a template edit reaches would be wrong eventually, and wrong here means a live site serving stale markup with nothing saying so.
• The facts the build hands to the record by name rather than by hashing a tree: the menu, which content types the archive holds, the address it is published at, and the timezone -- named by the contents of its zoneinfo file, so a system update that rewrites the rules of your zone throws the record away rather than leaving old times on skipped pages.
• Any page whose published file has been deleted, or has moved in size or timestamp since the build wrote it. The record is checked against what is on disk, never only against itself.
• A record that is missing, half-written or unreadable. Deleting .build_cache.json is always safe and costs one slow build.
• A build that died halfway. It writes no record at all, because a record of a site half written would make the next build skip the half that never got written.

./blog.sh rebuild --full is the switch for the rest: render everything, compare everything, believe nothing. It is the escape hatch, and it is how the record is tested: a cached build and a full build over the same content must produce byte-identical trees.

What it costs

With no version in its URL, getting a changed stylesheet to a reader is the host's job: it works where files carry an ETag and are revalidated on each load, and a host that caches hard will serve the old one until it expires. And backdating is untouched by this: a post dated 2003 shifts every listing page between the front and where it lands, and those pages really did change.

A way out of the trash and the versions

Both stores had a way back — restore, and the version picker in the post's properties — and no way out, so both grew for years and nothing said by how much. empty trash and empty versions each print what they are about to remove, in items and in megabytes, and require that count typed back before anything goes. empty versions keeps each post's newest version, because versions exist to answer "give me back what I just overwrote". doctor now notes a trash with posts in it, as a note rather than a fault: on the installation this engine was built around, the only way to see it was du on the server.

A photograph stored once

public.nosync/ used to hold a second copy of every picture. It holds a hardlink now, so the pictures take half of what they did — 1.8 GB on this project's installation. It saves nothing in a backup, and that was measured rather than assumed: 200 files under two names, 101 MB on disk, 201 MB in the backup. Nothing to do; the first build after the upgrade makes the links.

check knows a type it does not know

type: story was stored on the post and read by nobody — no listing, no menu entry, no icon, and not a word about why. check names the eight types it knows now, and the route somebody reaching for a ninth usually wants: a tag named in nav:, which gives a listing with its own pagination, a menu entry and an RSS feed. Asked for in issue #42.

What three reviews found

The engine, the new page and the receiver each went through a review before the tag, by someone whose job was to break them, and every finding closed with a test that fails on the old code. Four of them are worth knowing about even if you never meet them.

Two posts written at the same instant left one post. Settling a post's name and writing its file were two steps with a media copy between them, and a copy with photographs takes seconds. Two runs that started together — a delivery from a phone while an import ran, two phones one after the other — were both told the name was free, and the second one's file replaced the first one's. Both callers were told it had gone well. The name is taken by creating the file now, which of two runs asking at the same instant only one can do; the other walks on to the next serial, and both posts survive.

./setup.sh | tee setup.log echoed the access token in clear text. The prompt hid what was typed only when both streams were terminals. Anyone who set a site up that way should assume the token is in that log and rotate it.

Attaching a photo through a symlinked directory in incoming/ deleted the original. ln -s ~/Pictures incoming/photos is the obvious way to stop copying photographs twice, and the tidy-up after a save compared path text, which follows no symlinks — so every original behind that link was inside its reach.

An embed could still smuggle a script past the sanitiser, in three spellings: <svg/onload=…>, javascript: written as an entity, and an <animate> whose values were a script. The pass now walks a tag's attributes and asks each one what it is, rather than matching shapes. It is the same guard that dresses a tag's own icon_svg.

Eleven places where a terminal was watching

The engine behaved differently in eleven places depending on whether a terminal happened to be attached — a question that flushed only on a tty, a key offered on screen and accepted everywhere, a tag with a letter outside ASCII that crashed under docker exec and cron, where LANG is unset. Nine of them are named in the changelog. All of them matter more now that a post can arrive from a cron job or a phone, where no terminal is ever watching.

Full notes, all of it, in CHANGELOG.md under 1.6.

./blog.sh add post.md

does the same work with the markdown handed over instead of typed. No editor, no questions, no dialog at the end. A bare filename is looked for in incoming/, so the file can arrive by the same upload as the photographs, and it is deleted once the post is written.

Where the wizard would ask, this refuses

A person can be asked. A script cannot, so every question becomes a refusal that writes nothing: a photo that has not finished uploading, an empty body, a file that is not text, a second filename where one was expected. The alternative — guessing — was measured on the old code, where a byte-order mark in front of the header was taken for body text: three invisible bytes from a Windows editor and the post arrived with no title and no tags, named after the words "title:" and "tags:", exit 0. 1.6 reads the header through them.

--json: one object, nothing else

With --json the answer is a single object on standard output. A post that was written carries slug, path, state, url, deploy and warnings, every key always present. A refusal carries ok: false, the reason as a code and one sentence.

And a refusal leaves with zero. That is deliberate, and it took a phone to learn it: iOS Shortcuts throws away the output of a remote command that failed, so every refusal a phone could meet came back as a bare status and nothing else — exactly when the reason was the whole point. The status answers the one question the object cannot: whether an answer arrived at all. A non-zero status means the engine is missing or the machine is not set up. Without --json nothing changes: prose on stderr and a non-zero status, as always.

Draft, unless the file says otherwise

The file stops at the draft. publish: yes in its front matter is the one thing a file may ask for that the wizard never could: to go straight out, the date settled, the announcement sent, the site rebuilt, the answer carrying the public address. A post sent from a train has no desk to come back to, so the choice is made when it is sent. Absent, or anything but yes/true/1, is a draft.

At a desk the same two decisions are flags: publish <slug> --yes answers the dialog in advance, and --no-announce puts the page up and sends nothing to Mastodon or Bluesky — toot can still send it by hand afterwards. One thing --yes will not decide for you: a post dated outside the recent window is published but not announced, and the run says so. Announcing is the one step that cannot be taken back.

--untrusted

Markdown that arrived over a wire gets one more rule: a picture reference may name only a bare filename. Without it, ![](/etc/passwd) reads the file into the post's media — right at a desk, where whoever typed it has the file anyway, and a door the moment the markdown comes from somewhere else.

None of this adds an API, a token or a listening port. A file is written somewhere the engine can see it, and a command runs. That is the whole integration surface, and it is the same one a person has.

On the archive this engine was built around — 6,639 posts, on the server it lives on — that was 47 seconds for a rebuild that changed nothing, and 48 from pressing publish to the post being out. Fine for one post in the morning. Less fine for fixing a typo in ten of them.

What the build remembers now

1.6 keeps a record of what went into each page: the post, the template, the locale, the configuration, the engine itself. On the next build it renders only the pages whose record no longer matches, and the rest cost one stat each instead of a full render and a read-back.

The same archive, measured the same way: a rebuild that changes nothing takes a seventh of what it did. Publishing a post dated today takes about two fifths — 16 seconds of build and 2 of upload, where it was 48 — and the build says so itself: Pages already up to date, not rebuilt: 10,160. The ratio is what travels; the seconds are one machine's.

What it still cannot skip

A post dated into the early 2000s costs four fifths of a full build, and there is no way around that. A post landing there moves every listing page between the front page and where it lands, and those pages genuinely changed. The cache skips what did not change; it cannot skip what did. Importing an archive is backdating several thousand times over, so an import is a full build, as it always was — which is also why an import should land in one go rather than post by post.

Editing a template, a locale or site.yml throws the whole record away, because any of those can change every page. So does a change of timezone, including the one a system update makes without you touching anything. A stylesheet is the exception worth knowing: pages link it, they do not embed it, so editing one changes the stylesheet and nothing else — the build after it renders the pages once more and finds nothing new to upload but the one file.

A note, not an authority

The record is an optimisation and never the truth about the site. Anything it cannot vouch for is built the old way: a record that is missing, truncated, in a different format, or left by a build that died halfway. A page somebody deleted or damaged by hand in public.nosync/ comes back on the next build, because the record is checked against what is actually on disk. And public.nosync/ is still swept of anything the build does not produce, cache or no cache.

It lives in .build_cache.json in the installation directory — gitignored, one per machine, always safe to delete. Deleting it costs one slow build and nothing else, which is the whole point of keeping the archive as files: the note about the files is just another file.

./blog.sh rebuild --full        # build every page again, then deploy

Nothing to migrate. The first build after git pull is a full one and writes the record; every build after it reads it.

A copy button on code blocks

Issue #44, from somebody running a blog full of terminal how-tos. It is always there rather than on hover: a phone has no hover, and a button only a mouse can find is one half the readers never get. Only on code blocks — a chat is a <dl>, inline code is a bare <code> — so it hangs on the block type, not on the tag. On an http:// install there is no button rather than a dead one, and it copies what the block stores, not what wrapped on screen.

Two things you will see

Every listing by content type has an icon now. The other four kinds of listing got theirs in earlier releases, which left these seven looking unfinished; the quotation mark is filled rather than stroked, because outlined at twenty pixels the pair closed up into something that read as the digits 99. And the page is framed on all four sides: a heavy rule has closed it off top and bottom since 1.3, but the sides stayed open, so on a wide screen the text had a beginning and an end and no shape. Off below 700 pixels, where the column already reaches both edges.

Where one paragraph ended and the next began

A search snippet is a post's text with the paragraphs taken out, so the last words of one and the first of the next meet as one broken sentence. A middle dot stands between them now — not an ellipsis, which already means "cut here" at the end of every snippet, and one mark with two meanings is how a reader learns to trust neither. On the reference archive, 593 of the 1,636 titled posts run past their first paragraph.

The appearance button, in a window that refuses to remember

Safari's private windows — and any profile with site data blocked — throw when localStorage is merely read, not only when written. That threw out of the last line of theme-toggle.js, so the code wiring the button up never ran: no cycling, no symbol, nothing. Both sides are guarded now, and the cycle asks the page which theme it is showing rather than the storage it may not have.

Thirty-four lines of your own configuration

Choosing a palette in ./style.sh deleted them. The last colour key is the last active key in its section, and the commented-out fonts: block underneath holds a line that uncomments to the same indentation as a colour — so the writer claimed it, and everything below it, as part of what it was rewriting. The file came back without its documented block, and the wizard reported success.

The other door to a photograph

./blog.sh add strips the coordinates out of a photograph, exactly as the documentation promises. ./blog.sh edit — the path people use far more — had grown a bare copy of the same work, and did not. Two implementations of one promise is one too many.

01.JPG and 01.jpg

An importer keeps the source URL's extension exactly as it was, case and all, and 01.JPG is an ordinary name in a real archive: Posterous served IMG_2669.JPG, and a decade of cameras wrote nothing else. The allocator compared bytes and handed a new picture 01.jpg believing it free; the copy asks the volume, and on macOS, or any Windows share, 01.JPG answers for 01.jpg. So the copy was skipped, the arrival's bytes were never written anywhere, the post showed the old photograph under both names — and check reported a reassuring "misnamed". Names are folded on every volume now: one that is free on Linux and taken on macOS is a picture that vanishes when somebody moves their site.

Somebody else's stylesheet, inside your post

An imported embed's HTML was rendered with its scripts, style blocks and stylesheet links intact. The site's policy already stopped the scripts — but the feed carries the same HTML and has no policy at all, and the style block was never inert anyway: style-src has to carry unsafe-inline for a post's own colour formatting. Both Instagram embeds in this house's archive carry body > iframe { min-width: auto !important }, reaching out of the embed to every iframe on the page. Nothing hostile; simply not this site's to decide.

On the real front page that meant fourteen cards carrying between 794 and 2,616 pixels of content and showing 500. Of the page's 50,659 characters, 49,312 sat inside the clip. Thirty-three of its 154 focusable elements could be reached with the keyboard while being invisible on screen — links a sighted mouse user could not see and a keyboard user could not skip.

1.5 cuts the card before it is written. The stylesheet hides nothing.

That page went from 89,268 bytes of HTML to 41,155. Its largest card, 7,463 characters, is now 2,566. And "read more" appears exactly when something did not fit, rather than sitting under a card that was already showing everything it had.

The budget is in pixels, not characters

This is the part that had to be measured. A character budget is the obvious design and it is wrong, because characters do not measure height. A picture costs no characters and several hundred pixels. Written as a rule of "400 characters", the cut made 34 % of this archive's cards taller than the clip it was replacing — one of them 4,928 pixels tall.

So the budget is an estimated height, read off a real card: a 534-pixel content column, a 24-pixel line, about 78 characters to a full line, checked against twelve real paragraphs — eleven of which agreed. The estimate is approximate on purpose. The reader's column is narrower or wider than the nominal one, and so was the 500-pixel clip it replaces. What matters is that the cut lands between blocks rather than through one.

What is never cut

A picture. If the first block is a photograph it is kept whatever its height, because on a photo post the photograph is the post, and a card that opens with a cropped image is worse than a card that runs long.

A block made of rows — a hundred lines of shell, a long conversation, a list, a table — is cut to the rows that fit, at a row boundary. A paragraph that runs past the budget is cut on a word, with its formatting cut to match, so a link cannot end up pointing past the text it decorates.

And an author can overrule all of it

A line reading //--more--// splits a post into what it says about itself and what it actually says. The listing card, the link card and the announcement take the first half; the post's own page shows everything.

That one was asked for in issue #35 by somebody else running the engine, and their complaint was exact: a machine cut rarely lands on a good sentence, and the author knows where theirs is. A height budget is a decent guess about a card. It is not a claim to know where your post stops being an invitation.

1.5 adds two pages that read the archive instead of walking it.

/archive/ — the shape of the whole thing

A row per year, with a strip of twelve months beside it. A month is shaded in one of four steps rather than simply lit or dark, because "has posts / has none" is not the question worth answering: on the reference archive a month holds anywhere from one post to eighty-seven, and drawing those the same would hide the one thing a map is for. /archive/<year>/ is one line per post, by month.

Two levels and no more. A third would be some 280 pages of individual months — a great deal of building for a question nobody asked.

It is an index, not another listing: no excerpts, no pictures, no cards. And it is cheap by construction. Publishing a post rewrites the map and the current year; 2014 has not changed since new year's eve 2014 and never will, so a deploy that compares content has nothing to upload for it, ever again.

/tag/ — every subject the site has

The engine has always built a page per tag and never anything that showed them all. A site's own list of what it writes about lived in browse, or in the top eight of stats.

The list is sorted by the folded name, and that is not a detail. Ruby sorts strings by bytes, which puts every accented tag after z: on one real archive that is fifty-two of them, and the last six in byte order are školení, školitel, šumava, švihov, želnava, životvkorporátu. A reader looking for one of those between sirky and sport would not find it. stats folds now too — one question should not have two answers.

Each tag is a pill with its count riding inside it as a superscript, so a line that wraps cannot strand a number beside the wrong name. A reader can switch the order to by-count and the choice is remembered. But the page is built alphabetically and the switch is a script on top of it: a reader whose browser never runs that script gets the order the markup already holds, rather than a control that does nothing.

Nothing to configure

Both pages are made out of the posts. There is no list to maintain, no front matter to add, and nothing that can drift out of step with what the site actually holds.

Every tag that has a page appears and no others. A tag carried only by a draft, a page or an unlisted post is drawn under its post as a flat pill with no link — listing it here would point a reader at a 404, and an index that lies about one address is an index you have to check.

--repair walks it with you

check --repair is the checker's other half: for each finding it offers the one repair that finding allows — an old address written into the target post's redirect_from, a relative link rewritten to the address it means, an orphaned file moved to the trash. Nothing is applied without a keypress, nothing is deleted outright, and a finding with no obvious answer — two posts colliding, an image only a human can judge — is shown and passed over rather than guessed at.

It proved itself before it shipped: on a real archive it took 238 findings down to 42, and the 21 repairs it proposed matched what a person had already decided by hand, one for one.

--json says everything

The screen shows twenty of a kind and totals the rest — right for reading, useless for a script. check --json prints every finding, uncapped, each with its kind and its data, so anything that wants to act — a migration script, a cron report — works from the same facts the screen summarizes.

And check itself got stricter

The rule behind the new findings is one sentence: an archive check calls sound must be one the build will run on. A file that will not parse, a date nothing can read, text that is not a list of blocks, a slug that is not one path segment — each is now a finding, because each is a build that stops. The one tool whose job is to say otherwise no longer says "sound" about any of them.

Sixty sentences moved home

1.4 finishes the job: the deploy's whole narration — header, progress, the closing tally, every degradation notice — plus all eleven build warnings, every Bluesky and Mastodon failure, and the sentences an import prints when a source dies. English, Czech and German carry the same set, and the suite enforces the parity, so a key cannot exist in one language and abort in another.

What stays as it arrived

The diagnostics inside the sentences do not get translated: an HTTP code, a server's raw answer, an exception's text. Those are evidence, and evidence is quoted, not paraphrased — the sentence around them is the site's, the thing inside it is the network's.

The plural trap

"Built 1 posts" is the kind of bug a translation multiplies — Czech declines counts three ways, German differently again. The counted lines are written label-then-number now (posts: 1), which no language has to decline. Boring is correct, and correct in all three at once.

Pages

page: true gives a post a permanent address at the root — /about/ — out of the listings and the feeds, but in the sitemap and the search index. Ghost, WordPress, Squarespace and Substack import them as pages now instead of skipping them, and the import says where they landed and that nothing links to them yet. The engine will not write a nav: entry on your behalf; where a page belongs in your menu is your decision.

Series

series: groups posts and series_part: orders the one you published out of turn. Each series gets a listing, and every post in one links to the previous and next part — within the series only, never spilling into the archive around it. A draft's preview says whether its series name joins something that exists or founds something new, so a typo is caught while it is still free to fix.

Unlisted

unlisted: true keeps a published post on its ordinary address and takes it out of every listing, feed and index, noindex included. It is the draft's hidden address, generalised to a finished post. Deliberately not a password: publishing one no longer announces it either, and --force does not open that door — take the flag off first, so the decision is explicit.

./blog.sh stats

The archive counted from the posts on disk. No build, no network, no env.sh. This site, at the time of writing:

The archive
  43 post(s): 43 published, 0 draft(s), 0 scheduled, 0 page(s)

What they are
  text      ██████████████████ 28 (65 %)
  link      █████              7 (16 %)
  chat      █                  2 (5 %)
  image     █                  2 (5 %)
  audio     █                  1 (3 %)
  document  █                  1 (2 %)
  quote     █                  1 (2 %)
  video     █                  1 (2 %)

Words
  17,048 words in all, 396.5 per post on average, 416 in the middle
  longest: what-rots-quietly (828 words)
  reading the whole archive takes 1.4 hours

Media
  24 file(s), 27.6 MB, across 10 post(s)

Words carry both mean and median, deliberately: here they nearly agree, because these posts are all the same kind of thing. On an archive half made of imported tweets the mean sits far above the middle, and only the pair says so. --json prints the same figures unrounded.

Reading time and a table of contents

Reading time on every post page, and on every listing card, because the deciding happens in the listing and reading time is the one thing every post can report. A post too short to time says "under a minute" rather than rounding itself to zero. A contents list appears from four headings up, or whenever a post asks for one with toc:.

A feed per tag

For the tags the menu names, with autodiscovery on the tag's own page. Not for every tag in the archive — on a real archive that is thousands of files, rebuilt and re-diffed on every build, that nobody will ever fetch. A tag in nav: is the site saying this is a subject I publish on, which is the same statement as somebody might want to follow just this. A site still using the derived menu gets no tag feeds at all; that is the answer, not an oversight.

fediverse:creator

Mastodon puts the author's account on a shared link's preview card. No new configuration key — it is the social: entry already pointing at a profile on the instance the site announces to.

Blocking the training crawlers

seo.block_ai_crawlers writes a maintained list of them into robots.txt, and seo.robots_extra takes free text for whatever else you want in there. Off by default, and worth saying plainly: robots.txt is a request, not a fence.

A 404 page

Built by the site rather than left to whatever the host shows: the menu, the search field, noindex, and a signpost under the heading drawn inline in the palette's own colours, with its one accent arrow pointing the way on. A dead end on my site should still look like my site.

Keyboard, phone, and a search that ranks

Every page has an h1 now — listing headings were level two, and the front page had none at all. Focus is visible again, in the accent. prefers-reduced-motion is honoured, so transitions collapse and the back-to-top button jumps instead of scrolling. The lightbox can be opened, walked and closed without a mouse. On a phone the menu closes with Escape or a tap outside, and the search field sits in the bar rather than folded into the menu.

Search itself answers with its best results instead of its most recent ones — a title outranks the text, a whole word outranks the same letters inside a longer one, ties keep their date order — and a search has an address again, so ?q= can be sent, bookmarked and returned to.

./blog.sh check walks all of it and says.

What it looks for

Each finding names a post and a slug — something to go and fix — and carries a line saying what to do about it.

• Media a post asks for and hasn't got, a video's poster included. Usually an import whose download failed. The page renders a hole.
• Images stored as 1px or smaller. The build treats those as tracking pixels and drops them together with their caption, so the page loses both without saying so. That one had been happening for a while before anything looked for it.
• Internal links pointing at nothing — typically a permalink left over from an import.
• Media directories no post owns, left by a deleted post or an import that ran twice. They cost disk, not correctness, so they are warnings.
• Files in a post's own directory that the post no longer names. An import only ever adds, so a source that drops a picture between runs leaves its file stranded.
• Two series whose names differ by a character or two — one series with a typo that quietly founded its own. Names differing only in digits are left alone: rok-2025 beside rok-2026 is two year-series, not a mistake.
• One old address claimed by two posts. Whichever renders last wins and the other's readers land on it.

What it said about this site

Checking this archive

Reading posts: 37/37

⚠️  Post fourteen-years-every-image-came-home no longer names the file
   01.jpg in its media directory.
   Left behind by a picture the source dropped or renamed between
   imports. The post does not reference it; delete it yourself once you
   have looked.

0 problem(s), 1 thing(s) worth a look.

One warning on a small, carefully kept archive, and it is the finding this release added. The fix line guesses at an import, because that is the usual culprit — but nothing on this site was ever imported. That stray file was mine, and its story is duller and more ordinary than any import. I wrote that post one morning; forty minutes later I added a screenshot to the front of it, everything below shifted one place down, and the picture that had been 01.jpg was written again as 02.jpg. Same bytes, same checksum, new name. The post went out that evening carrying six pictures, and the seventh — the old name of one of them — sat in its directory for the next two weeks, 124 kB that nothing pointed at.

Which is the better argument for the check than the one I had. It doesn't care who left the file, and here it caught a case where nothing was lost and nothing was broken — just a copy of a picture the post still has, under a name it no longer uses.

The file is gone now, and running it again says so:

✅ Nothing wrong inside the archive: 43 post(s), with media, links and
   redirects all checking out.

The archive is sound.

It only reports

Nothing here deletes a directory or rewrites a post. The value of a checker is that its output can be trusted, and a checker that also acts has to be trusted twice.

It exits non-zero on errors alone, never on warnings, so it can hang off cron and speak up only when something is actually broken. Long lists are capped at twenty lines per kind — but the counts in the summary are the archive's, not the screen's, so one bad import cannot bury everything else and cannot flatter the totals either.

--online is a different tool wearing the same name

It asks the web about every link that leaves the site, and it takes minutes rather than a second, which is why you have to ask for it by name.

What it is willing to call dead is deliberately narrow: a host that no longer resolves, and a page answering 404 or 410. A timeout, a refused connection, a 5xx or a 403 is the web saying not right now — reporting those would turn one flaky evening into forty findings that are all fine tomorrow. Anything that looks dead is confirmed with a second request before it is believed, because some servers answer a HEAD with 404 and a GET with 200 for the same address.

Verdicts are remembered for a fortnight, so next week's run only asks about links it hasn't seen lately.

The hardest part was not finding things

It was not finding things that aren't there. The first honest runs called a healthy archive broken: every internal link into a listing page, a tag page or a series page came back dead, because those addresses are written by the build and check reads the content. A checker that exits non-zero every night on a sound archive trains you to ignore the night it means it.

One deliberate exception survives that pass. A link to a series with only one published part is still reported, because a series listing exists from the second part on — the address really is empty today, and it starts working the moment you publish part two.

./blog.sh doctor reads what is on disk and tells you the lot in one pass, in whole sentences, each with a fix line written for somebody who does not know which file that setting lives in.

It goes after the silent failures

A loud error at least announces itself. The problems doctor concentrates on are the ones that never say anything:

• An unknown timezone. Ruby falls back to UTC without a word, and every post is dated wrong from then on.
• A banner whose declared size no longer matches the file. Every page jumps as it loads, and nothing anywhere is broken enough to complain.
• A widget that can never show anything — configured with the wrong kind of identifier, rendering an empty box forever.
• A font named in the config but missing from assets/fonts/. The browser silently falls back and the site is simply not the site you designed.
• A deploy backend configured half way.
• The example's text still sitting where visitors would read it — the about box that still describes a blog engine's sample site rather than yours.

--online additionally asks whether the feeds, the analytics script and the access token still answer. Tokens expire quietly; that is their nature.

It runs when nothing else will

This is the part that took the most care. Doctor works on configurations too broken for anything else to load — including one whose YAML will not parse, which is exactly the moment you want it.

Related, and shipped alongside: a YAML syntax error in config/site.yml is now a sentence rather than a Psych backtrace from whichever entry point happened to read the file first. It names the line, the column, the three usual causes — a tab where spaces belong, a missing quote, a colon inside an unquoted value — and points at doctor.

Errors and advice are different things

Exit status is non-zero for errors only. Warnings are advice, and advice that fails your build is not advice.

That distinction is why doctor is safe to put in a cron or a pre-deploy check: it will stop you when something is actually wrong, and merely talk when something is merely worth knowing.

Why bother, on a tool this small

Because "it doesn't work and I don't know why" is where people give up, and the engine's own failure modes were the ones most likely to produce that sentence. The abort messages were all accurate. Accuracy one problem at a time is still a maze.

Renaming a post changes its address. That's unavoidable — the slug is the URL. What's avoidable is the old address turning into a 404.

What renaming does now

Rename a post — r in the properties dialog — and the post records its old address inside itself. The build then keeps a one-page redirect standing at every address the post has ever had.

The link in a two-year-old toot keeps resolving. The link somebody put in their own blog post keeps resolving. You get to fix a slug you regret without the fix costing you every reference to it that already exists in the world.

The redirects belong to the post

They live and die with it. Unpublish the post and its redirects come off the site with it — a redirect pointing into nothing is just a slower 404. Publish it again and they come back, because the old links didn't stop existing while the post was away.

That's the same rule the announcement toot follows, and for the same reason: everything a post owns should leave and return with it, or the site accumulates debris nobody remembers creating.

The small print

The redirect list is the post's own history, so it never contains the post's current address — a post redirecting to itself is a loop, and the build says so if a date edit across a year boundary ever creates one.

And slugs have a length limit now, with a plain message when you exceed it. The first version handed you a filesystem error instead, which is a technically accurate way of saying nothing useful at all.

The claim first: zero gems, zero npm packages, no Bundler, no lockfile, no node_modules folder quietly gaining weight in the dark. Ruby 2.7 or newer and bash. Clone it and it runs.

The asterisk, up front

Two optional sidebar widgets — Pixelfed and generic RSS — parse XML with rexml. That's a default gem: it ships bundled with every normal Ruby installation, so for most people the claim holds as written. But some Linux distributions split Ruby into packages and put the default gems in a separate one.

So: if you enable those two widgets on a distro-packaged Ruby and the build complains about rexml, you're the asterisk. Two ways out — install your distro's ruby-rexml-ish package, or gem install rexml. Either way it's one package, once, and only if you use those widgets at all.

That's the entire dependency story. I'd rather write it out than round it down to zero and wait for someone's build to disagree.

What a real zero buys you

No network dependencies at build time means the entire site builds offline. On a plane, on a train, on a server that firewalled itself into a corner — ruby build/build_blog.rb neither knows nor cares.

And the output is as boring as the input. Measured on this site, today, fourteen posts:

That JavaScript is the complete inventory: theme toggle, lightbox, client-side search, the comments loader, sidebar widgets, mobile nav, scroll-to-top, and a shared utility file. No framework is hiding under any of them.

And yes, a second asterisk snuck into the table, same policy as the first: the one third-party request is my own self-hosted Umami analytics, on another domain of mine, added through the config. The engine itself ships exactly zero — no fonts CDN, no tracker, no embed phoning home. Turn the analytics line off in site.yml and the number is a structural 0.

Why bother

Because every dependency is a small standing appointment with the future. Some Tuesday it needs updating, audits, replacing, or it deprecates the one function you used. A stdlib-only tool skips those appointments — the price is writing a bit more code yourself, and for a blog engine that price turned out to be surprisingly low.

A zero with its exception written down is more useful than a zero without one. If you trust the asterisk, you can trust the rest of the table.

That's the whole feature: the deploy assumes a large change is a bug until you say otherwise.

How it works

Every deploy keeps a manifest — SHA-256, size and mtime for each uploaded file. The next deploy diffs against it and only touches what actually changed. Fast, boring, correct.

The interesting part is what happens before anything uploads. If the file count dropped by more than 20% since the last deploy, the whole thing stops. This is real output from this very site — I parked half the build's folders out of sight for a minute and asked for a deploy:

❌ Stopped: public.nosync/ has 28 files, but 62 were uploaded last time.
   That's a 55% drop -- looks like a broken build.
   Check the build output. If the drop is expected (you deleted a lot of posts), run again with --force.

A drop like that almost never means "I deliberately deleted half my blog." It means a typo in a path, an empty content directory, a build that crashed halfway. Without the guard, --prune would cheerfully delete the rest of your live site and upload the wreckage.

And it's symmetric: a sharp increase trips the same wire, because a site that suddenly doubled usually means a duplicated tree or a badly merged import, not a very productive afternoon.

The escape hatches

• --dry-run shows exactly what would upload, change or be deleted — and touches nothing. Here's today's, after editing two posts:

Deploy web -> Surfer: https://blogsh.app  [DRY-RUN]
  62 file(s) total, 10 new/changed, 52 unchanged (skipped)
  [dry] index.html (54990 B)
  [dry] posts/2026/no-gems-one-asterisk/index.html (14852 B)
  [dry] posts/2026/why-not-x/index.html (14584 B)
  [dry] rss.xml (38156 B)
  [dry] search-index.json (29072 B)
  ...

Two posts changed, so ten files upload: the posts, the pages that list them, the feed, the search index. Everything else is a checksum match and stays home.

• --force is the "yes, I meant it" switch, for the day you really do delete a hundred posts.
• --prune is the only destructive flag in the toolbox, and it's opt-in. (On the git backend every deploy is a snapshot anyway, so pruning is implicit — and reversible.)

One honest side effect

Do a bulk import — or publish a fourteen-post series in one evening, as this site just did — and the growth guard trips too. Again, real output, from this site's launch night:

❌ Stopped: public.nosync/ has 63 files, only 30 were uploaded last time.
   That's a 110% increase -- looks like a duplicated or broken build.
   Check the build output. If the increase is expected (a bulk import/migration), run again with --force.

That's not a bug; that's the guard doing precisely its job on the one occasion you'd forgive it for staying quiet. Check the numbers, feel briefly smug that something checked them at all, and run it again with --force.

What you type:

Posts are **files**. The build is a loop over a folder.

There is no step three.

What lands on disk, one JSON file per post:

{
  "slug": "no-step-three",
  "title": "No step three",
  "date": "2026-07-31T09:00:00+02:00",
  "state": "published",
  "tags": ["content"],
  "content": [
    {
      "type": "text",
      "text": "Posts are files. The build is a loop over a folder.",
      "formatting": [
        { "type": "bold", "start": 10, "end": 15 }
      ]
    },
    {
      "type": "text",
      "text": "There is no step three."
    }
  ],
  "source": { "platform": "manual" }
}

(Trimmed for the post — a real file carries a couple more housekeeping fields — but this is the real shape.)

Look at where the bold went

The text is plain text. The bold is a pair of offsets pointing into it — not <strong> tags baked into a string, not a Markdown blob waiting to be parsed again. That one decision quietly pays for half the engine:

• Search indexes the text as-is. No stripping tags, no "why does searching for strong match every post".
• The build never parses Markdown. Parsing happens once, at save time; the build just renders blocks it already understands.
• Importers from seven platforms all target this same schema — which is why a new import source is an adapter with three methods, not a fork of the parser.

Round trips, with a seatbelt

edit converts the JSON back to Markdown, you edit, it parses again on save. And when a post contains something Markdown can't express — an embed imported from Bluesky, a link card — the editor warns you before saving would flatten it, and asks. Nothing gets silently thrown away in the round trip.

The boring finale

One post is one file, and I mean that as infrastructure, not poetry:

• backup is tar
• history is git
• migrating away from ./blog.sh is a for loop over a folder of self-describing JSON

And one consequence worth saying out loud: the deployed site is just a build artifact. The working copy — content, media, config — lives on your machine, entirely under your control, no matter where the web part runs or what happens to it. Host disappears, server catches fire, provider triples its prices? Nothing of value was there. You point the deploy at a different backend and the site exists again, byte for byte. The server was never the blog. Your folder is.

An engine should be easiest to leave the same way it was easiest to join. This is that, in one file per post.