philosophy – ./blog.sh

Whoever loads last wins

Sat, 19 Sep 2026 09:49:45 +0200

Two real sites wear a look this engine never shipped. sh.cynicky.blog is dressed as Ghost — a full-width lead card, a dotted frame, tiles instead of a plain list. arch-linux.cz is dressed as a Hugo theme, Blowfish specifically — a compact bar, a profile block, cards laid out like someone else's homepage entirely. Neither forked the engine. Neither edited a template. Both still take a plain git pull.

One stylesheet, loaded last

site.extra_css in config/site.yml names a path, or a list of them, loaded after the engine's own colors.css and site.css. That's the entire mechanism — a skin is one file of yours that repaints what's already on the page, and the engine never writes to it, so an update can never conflict with it.

Local paths only: every page carries style-src 'self', and a stylesheet on another host would just be dropped by the browser with no error anyone would ever see — the build refuses a remote path out loud instead, before that silence has a chance to happen.

Whether that file belongs in git is a separate decision — commit it and a second machine already has your look, exclude it and a public repository never carries a design that wasn't meant to be public. The engine's own .gitignore doesn't decide this for you either way.

The rule everything else follows from

Loading last means your rules win at equal specificity — including the rules the engine wrote for narrow screens, which is not the part anyone expects to be winning against.

sh.cynicky.blog's skin floats a table of contents beside the article and gave it a percentage width to match its own measure. On a desktop that looked right. Below 700px, the engine has its own reflow: the contents drop above the text and the width rule becomes auto, because there's no room beside anything at that size any more. The skin's percentage didn't know that and kept applying anyway — loading last means winning always, not just when it's convenient to. The article came out 155 pixels wide on a 390-pixel phone screen.

The fix wraps the override in the range where it's actually meant to apply:

@media (min-width: 861px) {
  .toc { width: 350px; }
}

Below that width, the skin says nothing, and the engine's own reflow is left to do the one job it was already doing correctly.

What the engine leans on without saying so

Two smaller traps came out of the other skin, arch-linux.cz's, and both share the same shape: a rule that looks purely decorative turns out to be load-bearing somewhere else.

Unsticking the engine's nav bar is a reasonable thing for a skin to want. On arch-linux.cz it also made the theme-switch button stop responding to clicks — not because the button broke, but because the bar sat in a CSS grid, where z-index takes effect without needing position at all, and the unstuck bar kept its higher layer sitting invisibly on top of the button. The site's own admin found it by actually clicking the switch; nothing in a screenshot would ever have shown it.

A second, smaller one: max-width on a flex item with flex-basis: 100% shrinks the item's hypothetical width rather than capping its contents — which is how an article body once ended up sitting beside its own meta line instead of below it. The cap belongs on the children, not the box around them.

One page of a listing, not the whole feed

A stylesheet can't read an address, so the front page and /page/2/ used to be indistinguishable to CSS — which mattered the moment either skin wanted a lead card on the first page only. Since 1.3.2 every listing's says which kind it is:

.page-first .post-list-item:first-child { /* the lead card */ }
.page-cont  .archive-note { /* only on the continuations */ }

Two classes rather than one, on purpose — a single mark on the continuations would mean writing the first page's look unconditionally and then undoing it property by property, and a rule that undoes another rule is the kind a later edit quietly stops undoing.

That's sh.cynicky.blog above — full-width lead card, dotted frame, tiles instead of a plain list, and not one edited engine file behind any of it. Its search stays a field in the engine's own bar rather than the modal Ghost itself would give it, because rebuilding it as one would mean owning behaviour the engine never promised. Neither skin, this one or arch-linux.cz's, ever tried for a pixel-perfect copy of what it imitates. Fidelity was never the goal. Belonging to the family was.

A skin stops being the cheap tool the moment it needs markup the engine doesn't build — at that point editing the template is the honest choice, not a stylesheet fighting to fake one. Short of that line, though, none of this needed a theme system: no hooks, no registry, no hierarchy of overrides to keep straight. One fact carries the whole feature. Your file loads last.

—

P.S. — sh.cynicky.blog isn't where cynicky.blog itself lives. The real site is still on Ghost, updated most days; sh.cynicky.blog is the same look, kept as a working installation of its own. Its author looked at a real migration and chose to stay where he already was — worth saying plainly, rather than letting a domain name imply otherwise.

The build doesn't know where it's going

Sat, 12 Sep 2026 19:26:30 +0200

Somebody builds a whole site on a laptop, imports a decade of old posts into it, previews every page — and none of it has gone anywhere yet. Nothing in env.sh says where, and nothing else is waiting on that: the build runs, the archive checks out, every page renders at localhost. The build doesn't know where the site is supposed to end up, and it doesn't need to.

The same build can start on a laptop, move to a rented VPS a year later, and land on a Cloudron instance after that. Nothing in the content pipeline changes between any of those moves. What changes is the answer to one question — where should the files go — and six things can answer it.

What decides it

DEPLOY_BACKEND in env.sh names the target; the values under it depend on which one. Everything past that line is identical across all six. Each backend keeps its own manifest — the SHA-256, size and modification time of every file it has already uploaded — so a deploy only ever sends what changed since the last one. deploy-web.sh --dry-run reads that manifest without touching anything.

Here's what that prints, run just now against this site's own backend:

$ ./scripts/deploy-web.sh --dry-run
== deploy-web.sh ==
Mode: preview (dry-run) -- nothing is actually uploaded.

Deploy web -> Surfer: https://blogsh.app  [DRY-RUN]
  Files selected: 194, 33.3 MB in the build, new or changed: 0, unchanged (skipped): 194

Nothing had changed since the last real deploy, so the manifest says so and stops there — the same sentence a git or rclone target would print, with a different line above it saying which one answered.

The manifest is per backend, though, so point the same build at a different target for the first time and that first deploy uploads everything — moving is one full upload, not a redo of anything the build did.

The strictest one sets the rule

A single file over 100 MB is refused at save time and again at deploy time, and the limit is the same number on all six backends — not because every target shares that ceiling, but because the engine picks the strictest one and holds everyone to it. A site built to run on rsync stays deployable on sftp without anyone finding out the hard way which backend was the forgiving one.

That's the tell that this isn't six uploaders sitting next to each other: it's one deploy model — one manifest shape, one safety guard, one file-size limit — with six ways to reach the far end. The backends differ in how the bytes travel; what's allowed to travel isn't theirs to decide.

The six

surfer is the default — set SURFER_URL and SURFER_TOKEN and nothing else needs saying. It's Cloudron Surfer, the host this project itself runs on.

local writes straight into a directory, for a docroot behind your own nginx or Caddy. HTTPS is the web server's job either way; the engine's CSP arrives as a meta tag, so there's nothing to configure on that front even without one.

rsync goes to any SSH host with rsync installed — the most universal of the six, since that describes most VPSes and a good share of shared hosting too.

git pushes to GitHub, GitLab or Codeberg Pages, force-pushing the whole build as a single commit on every deploy. A custom domain needs GIT_PAGES_CNAME set, because the host keeps that address in a file living inside the very branch the snapshot overwrites.

rclone reaches S3, R2, B2, WebDAV and whatever else rclone config knows how to talk to, with the bucket's own credentials kept in rclone's config rather than in env.sh.

sftp is for the hosts with neither rsync nor git: plain SSH, batch-mode sftp, one connection per deploy. Key auth has to be set up first — a batch job has no terminal to answer a password prompt, and the connection fails rather than waiting for one that isn't coming.

Which of those six a site runs on is a single line in env.sh, picked once and rarely revisited — because the harder half of the problem was never the backend. It was making sure it wouldn't matter which one got picked.

Written on a train

Fri, 04 Sep 2026 10:51:00 +0200

A reader who was thinking about moving to this engine wrote to say he would stay where he was. He manages his blog from a phone, on the road, and a blog that can only be worked from a terminal was no use to him however fast it built. He was right.

1.6 answers him with two things, and with one thing it refuses to do.

A page on the blog itself

Set write: true and the build publishes a small editor at /write/: a title, the text, tags, photographs and video, each picture with its description. It wears the blog it writes to — its name, its palette, its language — and it offers the blog's own tags as you type, the ones used in the last twelve months first, so a tag is tapped rather than spelt a second way. A preview shows the post in the blog's own stylesheets. A row of marks above the text wraps what is selected and comes off again on a second tap. Above the send button, a Draft | Publish switch.

Everything is kept in the browser between visits — the text in local storage, the pictures' bytes in IndexedDB, because five megabytes is all local storage gets and one phone video is more than that. When somebody interrupts you on the platform, nothing is lost.

The page is off by default, marked noindex, and holds no secret. It is served from the blog itself, so the same git pull moves both ends of the protocol and they cannot drift apart.

A key, and nothing new on the network

Sending is two iOS shortcuts. One takes the files from the share sheet, the other opens the connection, because the shortcut that receives files may not open one. The connection is the SSH the server already has, and the key lives in the shortcut, on the phone. On the server, that key runs one forced command: scripts/receive.sh, which takes the whole post over one connection — pictures first, the markdown last — checks every name and decodes every body before it writes anything, and hands the markdown to add.

Nothing new listens. There is no login, no session, no token in a form. A delivery over the ceiling hears too_large instead of a closed channel; one that goes quiet is dropped. The server's answer comes back to the page in the address bar, in the reader's language, and the draft is cleared from the phone once the server has the post.

What it refuses to do

It does not edit old posts. It does not delete, rename, schedule, back up or show statistics. It is one page on which a post can be written and sent, and nothing more.

That is the design, not the shortfall. Editing old posts from a phone would need what this engine has never had — accounts, sessions, a login — and the moment those exist, so does everything that goes wrong with them. A page that can only add, over a key that can only run one command, has nothing to defend.

What it costs

The first time is not two minutes: a key on the server, two shortcuts on the phone, one walk through the whole thing. Half an hour when nothing snags. The second time is opening a page and writing.

The page shipped in 1.6, two days of work after the message that asked for it. He was right, and the right answer to being told so is two days of work rather than a paragraph about why it has to be this way.

An archive you cannot see is not empty

Tue, 01 Sep 2026 16:22:00 +0200

This site's approved comments and its post counters are two small JSON files, refreshed by a cron job every half hour and uploaded with the rest of the site.

Through 1.4, a tick that ran while the archive was not there would narrow both files to nothing and upload them. An absent or empty content directory answers with an empty list and no error, and an empty list reads exactly like "every announced post was deleted". The live site lost every approved comment and every counter at once. Exit 0, nothing said, nothing mailed.

The archive lives on a synced volume. A volume that has not mounted yet, or a working copy whose files are still arriving, is not an unusual Tuesday.

Not being able to tell is a reason to keep everything

That sentence is the fix, and it now runs in two tiers.

If the content directory is not there — or if the archive reads as empty while the previous files held anything at all — nothing is narrowed, and the run says why.

And if only part of the archive is unreadable, a post file that will not parse this minute, a half-written save, a cloud copy still arriving, nothing is narrowed either. Otherwise that gap would be read as a post that was deleted, and its approved discussion deleted along with it. Only a run that could read the whole archive is allowed to decide that something is gone.

The same mistake, one job over

The scheduled-publish cron had a sibling of this. It took a snapshot of the due posts when it started and wrote that snapshot back when it finished, so everything that happened in between was overwritten. An edit made while it worked was silently replaced with the older text. A post deleted in the meantime was recreated from the snapshot, published, and announced to a timeline that cannot be recalled.

Each post is re-read at the moment it is written now.

Why these two are worth a post

Neither of them is a crash. Both jobs ran, both exited 0, both reported success, and one of them was announcing things to the world while it did.

That is the failure worth being afraid of in a tool that runs unattended: not the job that stops, but the job that carries on confidently with a wrong idea of what your archive contains. A crash you find out about. This kind you find out about when somebody asks where their comment went.

Posts nobody meant to publish

Tue, 01 Sep 2026 10:21:00 +0200

An importer's worst failure is not losing a post. It is publishing one.

1.5 went through all eleven import adapters and the machinery underneath them looking for exactly that, and found it three times over, in three different files, made the same way each time.

An archive is the whole account

A Mastodon export is not your public timeline. The outbox holds your followers-only posts and your direct messages beside the public ones — and every standalone toot in it was being written as published. On the archive this was measured against that is 141 posts of 2,548, of which 132 are direct messages, each given its own page, its own sitemap entry and its own item in the feed. Nothing in the run's summary mentioned it.

The scope was in the export all along, exactly where ActivityPub puts it. Public in to is public. Public in cc is unlisted — a real address, out of the listings. Followers-only and direct become drafts: that keeps the author's words in the archive and off the site, which is the only reading of "not public" that cannot publish something by accident.

Gated at serve time is not gated

Ghost ships the full body of every members-only and paid post in its export, because a Ghost site decides who you are when it serves the page. Read by anything that does not make that check, every word anybody paid for is plain text sitting in a file.

They arrived published, untagged and uncounted. They now arrive as drafts, tagged, and counted in the summary — the reversible half of the decision, and a number the person running the import can act on.

A comment on the wrong line

Hugo's TOML front matter says draft = true. Written as draft = true # nekdy pozdeji — a note to yourself, on precisely the line where a person writes one — the value scanner took the comment as part of the value. That made the flag a truthy string rather than the boolean it looks like, and a truthy string is not true, so the post imported as published.

Somebody's unfinished writing went onto the open web because they annotated the flag that was supposed to hold it back.

The rule underneath

All three are one mistake wearing different clothes: the importer treated anything it could not classify as public. The rule runs the other way now. Not being able to tell whether something is publishable is a reason not to publish it — and to say so in the summary, with a count.

An import you have to audit afterwards is one you cannot trust. The point of a number in the summary is that you should not have to go looking.

Tested like an enemy

Fri, 28 Aug 2026 16:52:00 +0200

1.4 went through four adversarial audit rounds before the tag: fleets of independent reviewers over real archives — real exports, a real 4400-post site, real deploy targets — each told to break the engine rather than confirm it. The findings numbered over a hundred. Every one was reproduced before it was fixed, and every fix is pinned by a test that demonstrably fails on the code it fixed.

The pattern that kept repeating

The uncomfortable lesson: each round's fixes were where the next round found its bugs. A fix for a comment-parsing rule deleted a hundred lines of somebody's config; a fix for that hid a widget's answers; the recovery advice written to save posts could destroy one. Four times in a row, the newest code was the most dangerous code in the tree — which is exactly why the last round audited nothing but the fixes themselves. It caught three regressions of mine before any user could.

Eighteen files

The proof I trust most is the quietest one. The whole release, rebuilt over a real 4400-post archive and compared byte for byte against 1.3.2, changes eighteen files: one stylesheet, two scripts, and one line in each draft preview. Published posts do not move by a byte. A release can rework the machinery this much and still owe its archive that kind of stillness — that is the contract, and now there is a diff that shows it being kept.

What you get out of it

Not a promise of zero bugs — nobody honest sells that. The promise is narrower and better: the failure modes that stay are the loud kind. check refuses what the build refuses. A crash cannot cost a post. A deploy pointed somewhere new uploads everything rather than trusting old records. When the next bug arrives, it should have to announce itself.

What a crash may cost

Fri, 28 Aug 2026 10:51:00 +0200

The queue can now swap two scheduled posts that share a slug across two years — with their media and their edit history riding along, because those are keyed by year and slug exactly like the post file. That sentence is short; making it true was most of a release cycle. The interesting part is not the swap. It is what happens when the power goes out in the middle of one.

The budget is zero

A move is several renames, and a crash can land between any two of them. The rule 1.4 holds to: whatever the moment, a crash may cost you the move — never a post. Files step aside under parking names before anything writes; a failed write puts everything back, byte for byte; a hard kill that strands a parked file leaves it where check finds it and says truthfully what it is.

The advice is part of the system

That last piece turned out to be the hardest. An early version of check's advice said "this is a stale copy — delete it", from nothing more than a file existing at the parked file's old name. But parking only happens when two posts share a slug, so the file standing there is by construction a different post — and after the right crash, the parked file is the only copy of yours there is. The advice now rests on the parked post's own identity: proven-stale names where the live copy sits; unproven says plainly that this may be the only copy, compare before you touch it, and never delete.

A recovery instruction that can destroy what it recovers is a bug like any other. It just took an audit aimed at our own fixes to see it.

My fixtures agreed with me

Mon, 24 Aug 2026 10:11:00 +0200

The importers had a good test suite. Every source had fixtures, the fixtures were parsed, the results were asserted, and everything passed.

Then I ran the importers over three archives I had not made: a Ghost export of 118 posts and 419 images, a Hugo tree of 77 files, and a WordPress WXR of 194 items. Alongside them, a fourth that is entirely mine — this engine's own export, read straight back in — because that one is not asking whether the code survives a stranger, it is asking whether the two halves of a round trip still agree.

The three foreign ones were the point, though. Fixtures had agreed with the code because both ends of them are mine.

The picture nobody failed to download

{{< figure >}} is how Hugo writes a picture, and the Liquid stripper ate it as a Liquid tag. Both of the ones in that archive pointed at files lying right next to the article in its page bundle: nothing to download, nothing that could fail, and they were gone without a line in the summary — because nobody had tried to fetch them, so nobody had failed.

That is the shape of every finding in this pass. Not crashes. Silence.

The promise that held for three per cent

Images come from the tree itself — no network. True of a Jekyll site, and repeated as a general promise about markdown trees in four places: the docs, the README's comparison table, the importer's header, and the comment above the adapter.

Of 79 image references in that real Hugo archive, 72 were absolute URLs pointing back at the WordPress the site had been migrated from years earlier. The import made 72 requests, 66 answered 404, and 20 of the 74 posts arrived with no pictures at all.

The summary reported all of that honestly. The documentation had told the reader there was nothing to report, so there was no reason to read it. All four places now say which half needs the network, give the number from that archive, and tell you to import while the old host still answers.

A fifth of a site with URLs in its headings

[](url) is what a WordPress-to-Markdown conversion leaves behind where a heading anchor used to be. The parser required at least one character of label, so it matched nothing and printed the raw markdown to the reader: 153 heading blocks across 14 of those 74 posts, square brackets and a full URL in the heading, five of them welded onto the end of the actual words. The table of contents linked to anchors named after github.com.

And a few more

A video uploaded to Ghost was lost and three lines of its player were published in its place. A percent-escaped filename was slugified character by character, minting permanent addresses beginning ef-bf-bc. An article that showed markdown inside a code block had its example eaten — and chasing that turned up something worse underneath: a paragraph ending in a picture came back a newline short, so the fence under it stuck to the text and every fence from there down was read inside-out, code as prose and prose as code. On that archive, 30 of its 72 images each did that to everything below them.

What the HTML converter has to drop — players, iframes, forms — was counted by exactly one of the eleven adapters that use it and thrown away by the other ten, so a WordPress import named its losses and a Jekyll import of the same body said "Done."

The lesson is cheap and I keep re-learning it

A fixture I wrote encodes what I believed when I wrote it. A stranger's archive encodes what actually happened to their blog over fifteen years, on platforms that changed under them, exported by a tool that had its own bad day.

Only one of those two can tell me I am wrong.

The way out ships with it

Wed, 19 Aug 2026 10:31:00 +0200

An engine that cannot hand your writing back is a hosting service with extra steps. The importers have always pointed one way — twenty-two sources, everything coming home. ./blog.sh export is the other direction, and it should have been there first.

What comes out

The whole archive as a tree of markdown files with YAML front matter, in the layout Jekyll reads: _posts/2026-05-01-slug.md, _drafts/, pages at the root, media under assets///. Old addresses travel as redirect_from, in the shape the jekyll-redirect-from plugin already understands, merging both kinds — where the post lived on the platform it came from, and where it lived here before a rename. Point a static generator at the folder and it builds.

./blog.sh export ~/my-blog-export        # everything, drafts included
./blog.sh export ~/public-copy --no-drafts
./blog.sh export ~/somewhere --dry-run   # counts, writes nothing

This site, counted rather than written:

Would write to /tmp/bsexport: 43 post(s), 0 draft(s), 0 page(s), and 24
media file(s) (27.6 MB).
9 block(s) markdown has no syntax for were written as HTML: link (6),
audio (1), file (1), video (1). Any engine that passes HTML through renders them,
and this engine reads them back whole -- each one carries its own
definition in a comment above it, which everybody else ignores.

The layout is Jekyll's: _posts/, _drafts/, pages at the root, media
under assets/. Hugo, Eleventy and Astro read it with a line of config;
./import.sh reads it as it stands.

What markdown has no word for

Plenty. An attachment with a label and a size, a video with a poster, a gallery, an embed — markdown has no syntax for any of it. Those blocks go out as HTML with their definition in a comment above them:

Any other tool sees ordinary HTML and renders it. ./import.sh reads the comment and gets the block back whole. That is the difference between an export that lets you leave and one that lets you move: export from one machine, import on another, and the installation arrives with its attachments still attachments.

It reads the archive, not the site

No build, no network, no env.sh. It walks content.nosync/ and writes. Which means it works on the day the config stops parsing, on a server you are being evicted from, on a clone you found in a backup — the moments when needing an export is not hypothetical.

The one guard: a directory that already has something in it is refused until you repeat the command with --force, which then writes alongside what is there. An export never deletes anything, at either end. A directory holding only dotfiles counts as holding something — a freshly cloned repository used to read as empty and get written into without the --force the guard exists to require.

Why it is in the engine and not in a script

Because a tool nobody maintains is a promise nobody keeps. The round trip — export, re-import, compare field by field — is in the test suite, and it earned its place there immediately: the first honest run found that an attachment came home as a paragraph with a link in it. Label gone, size gone, block type gone, file orphaned in the tree. Nothing had reported a loss, because both ends of the fixture were mine.

That is the argument for shipping the exit with the engine. A way out nobody ever walks is not a way out — and walking this one, field by field against what went in, is the only reason that defect was ever found.

A blog engine that became an archive

Tue, 11 Aug 2026 10:21:00 +0200

The first post on this site is about a photo I put on Instagram in 2012. The link still works. The photo doesn't.

That post was about one archive — mine — and one rule: media comes home. This one is about what happened when that rule was applied to every platform I could find an export for.

The roster is closed

Twenty-two sources import now, in three groups.

Social networks: Bluesky, Facebook, Instagram, Mastodon, Pixelfed, Threads, Twitter/X.

Blogs and publishing platforms: beehiiv, Blogger, Ghost, Jekyll/Hugo and any markdown folder, LiveJournal, Medium, Movable Type and TypePad, podcasts (any feed with audio), Squarespace, Substack, Tumblr, Wix, WordPress and any RSS or Atom feed.

And dead sites: the Wayback Machine, for blogs whose platform no longer exists at all.

Twenty-two sources behind twenty-one choices: WordPress and a plain feed share one

That last group is the one I did not expect to build, and it is the reason this post exists.

What changed isn't the count

An engine with eight importers is a blog engine that can read your old blog. An engine with twenty-two, covering every social network you are likely to have posted to, is something else: it is a place to put the things you wrote on other people's websites.

So here is the claim, plainly. This is a blog. You can also use it as an archive of your social networks. Point it at an export, and what comes out the other side is a folder of JSON files and the actual image and video and audio files, on your disk, with the origin recorded as a tag and every post reachable at a permanent address.

You do not have to put any of it on the web. The import writes the files and then asks whether to rebuild and deploy; answer no and the archive stays on your disk. An archive that only you read is still an archive.

Why the exports and not the APIs

Every importer here reads a file you asked the platform for, not a live API. That was a decision, and it holds up better every year: an export is a legal right in most of the world, it does not expire, it does not get repriced, and it does not need a developer account that a policy change can revoke. The three sources that talk to a network at all — Bluesky, Tumblr, LiveJournal — do it because those networks hand a public archive to anyone who asks, no token required.

The Facebook importer is built on Meta's own "Download Your Information". The Threads one reads the same export. Instagram, Mastodon, Pixelfed, Twitter, all the same shape: a file, not a permission.

The uncomfortable arithmetic

On the reference Facebook export used to build that importer, 95 % of the posts were mirrored in from somewhere else — Twitter, Posterous, the whole crosspost era. They are recognized and skipped, with a count, because those platforms' own exports carry the originals and importing both would double your archive with worse copies.

That number stayed with me. Nineteen out of twenty things on that account were not really written there. Whatever you think you have on any one platform, a good deal of it is a copy of something you put somewhere else — and the somewhere else has usually closed.

The point, again

An archive is only yours if the files are yours. Fourteen years was long enough to watch a few landlords disappear; twenty-two importers is what it took to stop renting.

Every source, and what each export does and doesn't contain, is in docs/importing.md.

The guard that switched itself off

Thu, 06 Aug 2026 20:47:38 +0200

This site's deploy has two guards. If a build suddenly has far fewer files than what's live, or far fewer bytes, the deploy stops. They exist because a broken build looks exactly like a deliberate one to rsync --delete, and a static site is only ever one confident sync away from being erased.

In 1.0 they could turn themselves off. Permanently. Silently. Here is how, because the shape of this mistake is more useful than the fix.

The reference was the wrong thing

The guards compared the new build against the deploy manifest — a record of what's on the target. Reasonable, until an upload fails. A failed upload leaves the manifest out of true, and a guard measuring against a record it knows is wrong would fire on every subsequent run.

So there was a marker: after a failed run, stand the guards down until a clean run comes along and restores the reference.

You can see it already. When the failure is permanent — a file the host keeps refusing, expired credentials, a target that no longer exists — no clean run ever comes. The marker never lifts. The guards are off, and nothing says so. A build collapsing from 7,500 files to a handful would have been mirrored faithfully, --prune included.

The fix was to stop measuring the target

They now compare the build against the last build that was accepted, recorded before the first byte moves. That number doesn't care whether the upload then succeeded, failed, or died halfway — so there's no longer anything to stand down, and no marker to get stuck.

The reference stopped being "what's out there" and became "what I last agreed to". Nothing else had to change.

Three more things came out of the same review

They also fired when they shouldn't. Twenty per cent of a 32-file build is six files, so publishing two posts at once could abort a deploy — inside a flow ./blog.sh runs for you, which has no way to pass --force. The percentages carry absolute floors now.

Bytes are guarded in both directions. The same file count with every page nearly empty used to be invisible. A byte drop stops the deploy; a byte increase only mentions itself, because attaching media is authoring, not a fault.

An empty build is refused outright. With an empty manifest, it used to sail through every check that existed.

Why write this up

Because "we found a bug" is worth less than "here is the reasoning that produced it". The bug wasn't sloppiness. It was a patch that solved the problem in front of it and created a worse one behind it, and it survived because the failure mode was silence.

The lesson I'm keeping: a safety mechanism that can be disabled by the thing it's protecting against isn't a safety mechanism. It's a suggestion.

Fourteen years, and every image came home

Fri, 31 Jul 2026 22:17:35 +0000

In 2012 I posted a photo to Instagram. The link still works. The photo doesn't.

If you kept a blog anywhere between 2010 and now, you know the drill. The platform got acquired, or pivoted, or "sunset some legacy infrastructure", and the images you embedded from their CDN quietly turned into grey rectangles. My personal archive goes back fourteen years across Tumblr, Twitter, Mastodon and a couple of other places — and a depressing number of its images now live at addresses that answer with nothing at all.

Here's what I mean, from my own archive. On February 22, 2012, I published a blog post called #53: Messengers of Spring? and embedded its photo straight from Instagram's CDN, the way everyone did back then. This is that link today:

distilleryimage1.instagram.com, fourteen years later

Notice it's not even a polite 404. distilleryimage1.instagram.com doesn't resolve at all — the photo is gone along with the entire piece of infrastructure that used to serve it. The post itself is still alive, imported into this engine, minus the one photo nobody can download anymore.

Here's the uncomfortable part: the post was mine. The photo was mine. The URL never was.

What the importer does about it

./blog.sh ships importers for twenty-two sources, and they all follow one stubborn rule: media comes home. Every image, video and audio file gets downloaded next to its post, into media.nosync///, and the post references the local copy from then on. No hotlinks, no third-party CDN, no "this content is no longer available".

A few details I'm fond of:

Downloads are measured on arrival. The build refuses to render an image without known dimensions — so the importer simply never writes one.
Failed downloads get retried. And when a file genuinely can't be fetched anymore, because the source deleted it years ago, you lose that one image — not the post.
The origin becomes a tag. Import an old Tumblr blog and every post lands tagged tumblr. Your old blog turns into a browsable archive instead of a zip file in a drawer.

The numbers

From a real migration of a real fourteen-year archive:

Source	Items in the archive	Notes
Mastodon	6,591	2,984 replies and 1,059 boosts skipped on purpose
Pixelfed	333	two accounts, 571 media attachments
Tumblr	1,099	four separate blogs, importing 1,247 media files that came home with them
Twitter	5,388	2008–2022, with 1,134 replies and 417 retweets in the pile — and 610 media files

Here's a handful from that archive — photos that spent years on one platform or another, and now live as files next to this post:

The Astronomical Clock — Hipstamatic, 2019

Prague Castle — Hipstamatic, 2019

Emauzy — Hipstamatic, 2019

Spholio, a sculpture at night — 2022

Shot on a Palm phone — 2019, because the archive keeps the weird experiments too

The point

None of this is clever engineering. Downloading a file and putting it in a folder is about as advanced as computing gets. The clever part was done by every platform that convinced us it wasn't necessary.

An archive is only yours if the files are yours. Everything else is a lease — and fourteen years is long enough to watch a few landlords disappear.

Why I built this (38 seconds)

Fri, 31 Jul 2026 22:17:31 +0000

Why I built this — 38 seconds, one take, recorded on a phone

Thirty-eight seconds, recorded on a phone, no edit. The written version is below if you'd rather read.

There are hundreds of static site generators. I wrote another one anyway, and the reasons fit in less than a minute.

My posts lived on big platforms for fourteen years. Some of those platforms changed the rules. Some just disappeared. I spend my whole day in a terminal, so I wanted to write my blog there too. And a small personal blog does not need a database — files are enough.

So: posts are files, the site is a build, and comments live on the Fediverse. That's the whole idea.

No gems (one asterisk)

Fri, 31 Jul 2026 22:17:25 +0000

./blog.sh needs no gems. Here's the one asterisk on that sentence, because a claim without its exception isn't worth much.

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:

Measured on this site	Value
Full build, cold	1.9 s
Full build, warm (only changed files written)	0.9 s
Homepage HTML	54 kB
All CSS	24 kB
All JavaScript	23 kB — 555 lines across 8 files
Requests to third-party domains	1*

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.

Why not X, and why Threads waits

Fri, 31 Jul 2026 22:17:21 +0000

Post read: $0.005 per resource. Post creation: $0.015 per request — $0.200 when it carries a URL. Free public read access: none.— X API pay-per-use pricing, docs.x.com, checked July 2026

Two networks are in. Two are not — and here's the whole reasoning, because "we decided against it" is not a reason.

./blog.sh announces every published post on Mastodon or Bluesky, and the replies to that announcement become the post's comments. For that to work, the engine needs two things from a network: a way to post, and a way for a browser to read a public thread. Cheap, ideally free, forever — because a personal blog is a decades-long project with a hobby budget.

X: no

Look at that price list again. Announcing a post with a link costs real money. Loading the reply thread — which happens every time anyone scrolls to the comments — costs real money, per read, forever. On a personal blog, that's a subscription to your own comment section, billed by your readers' curiosity.

There's no engineering answer to a pricing decision. So: no.

Threads: not yet

Threads is genuinely feasible, and the design is sitting in a drawer. But look at what "feasible" means here:

Publishing and reading replies to your own posts works — server-side only, through a registered Meta developer app, with OAuth and 60-day tokens.— the Threads API docs, summarized

In practice that's a cron job refreshing tokens so they never silently expire, and comments cached into JSON with roughly a half-hour delay — instead of the live thread Mastodon and Bluesky hand any browser for free. It's all buildable. It's just a lot of standing machinery for a network nobody has asked me about yet. The day someone does, the drawer opens.

Scraping Threads: no, and firmly

The tempting shortcut — skip the API, scrape the web app — fails three ways at once. The app's internals change constantly and no community project maintains a stable interface to them. Meta blocks datacenter IPs and forbids automated collection in its terms, so shipping a scraper in a community engine means handing every user a feature that breaks without warning and can put their account at risk. And the paid scraping services fail the same test with extra steps: per-request pricing, your data flowing through a third party, and a dependency on someone else's ongoing legal cat-and-mouse.

The scoreboard

Mastodon and Bluesky are in because they pass the boring test: free to post, free for a browser to read a public thread, no tokens with expiry dates in the critical path. Any network that starts passing it is welcome. Any network that stops — well, now you know the exit criteria too.

What ./blog.sh doesn't do

Fri, 31 Jul 2026 22:17:19 +0000

A feature list tells you what a tool wants to be. This is the other list.

Features that aren't there — and aren't coming

Multiple authors — the engine is built around one person's workflow, and every multi-author feature taxes the single author with roles, permissions and attribution UI
Plugins — a plugin API is a promise to keep internals stable forever; a tool this small should be forked, not extended
A WYSIWYG editor — your $EDITOR took you years to configure; I'm not going to compete with it in a textarea
Its own comment system — storage, moderation, spam, GDPR, and a database, all to rebuild what the Fediverse already does in public
Themes as downloadable packages — seven colour keys and your own banner get you further than a theme marketplace, at zero marketplace

Unchecked checkboxes, as rendered by the engine's own task lists. They'll stay that way.

What the parser refuses

The Markdown dialect turns things down too — each considered, each rejected, reasons attached:

Underscore italics (_like this_)
- underscores live inside ordinary text: file_names, snake_case
- the cost of supporting them lands on everyone who never uses them, as surprise italics mid-identifier
Code blocks indented with spaces
- collides head-on with nested-list indentation
- the backtick fence says what it means
Headings underlined with ===
- a line of dashes already means a horizontal rule and the frontmatter delimiter
- one more meaning for the same characters is one too many
Nested quotes (>>), reference links ([text][id]), footnotes
- each adds parser states whose main output, in practice, is surprising rendering of innocent text

Notice the pattern: it's the same reason every time. The cost of a feature lands on the people who don't use it — as complexity, as surprise, as one more way for plain text to mean something you didn't intend. A feature has to clear that bar, not just be useful to someone, somewhere, occasionally.

The upside of no

Every "no" above is load-bearing. No plugins is why a fresh clone runs. No WYSIWYG is why the whole thing works over SSH. No own comments is why there's no database, and no database is why backup is tar and migration is a for loop.

This list isn't an apology. It's most of the design.

Built for one blog on purpose

Fri, 31 Jul 2026 22:17:11 +0000

This is not a general-purpose engine, and pretending otherwise would waste your afternoon.

./blog.sh was built around exactly one deployment: one author, one archive, a terminal, and comments on the Fediverse. That's usually the part a project hides on the "about" page. I'd rather lead with it, because it's also the explanation for everything opinionated about this tool. A general-purpose generator solves the general case and then makes you configure your way back to your specific one. This engine started at the specific case and never left.

So here's the honest table:

	./blog.sh	Hugo	Jekyll	Ghost	WordPress
Database	none	none	none	required	required
Dependencies	Ruby stdlib*	one binary	gem ecosystem	Node + MySQL	PHP + MySQL
Comments	Fediverse, built in	bring your own	bring your own	native + members	native + plugins
Deploy	6 backends, guarded	bring your own	bring your own	it's a server	it's a server
Multiple authors	no	yes	yes	yes	yes
Plugins / ecosystem	no, on purpose	huge	huge	good	unbeatable
Community size	population: 1	enormous	large	large	a third of the web
10,000-post build	slower	seconds, wins easily	slow	n/a	n/a
Newsletter	no	no	no	yes, native	via plugins

(the asterisk is documented — one optional widget needs rexml on some distros)

Read the losing rows first; that's what they're there for. Hugo on ten thousand posts is dramatically faster, and if raw build speed on a huge archive is your constraint, take Hugo and my blessing. Ghost has a real newsletter business built in. WordPress has an ecosystem nobody catches up to, including a plugin for whatever you just thought of. A comparison table where the home team wins every row isn't a comparison — it's an ad with borders.

What the table can't show is the shape of the wins. "No database" isn't one row — it's why backup is tar, why hosting is any static server, why nothing needs a security patch on a Tuesday. "Comments built in" means the announcement toot, the reply thread and the unpublish cleanup are one feature, not three services on three bills.

Who this is for: one writer with a terminal, an archive they want to own outright, and an account on the Fediverse or Bluesky.

Who this isn't for: teams, clients, editorial workflows, anyone who needs a web admin, anyone whose readers must comment without leaving the page.

Built for exactly one blog — which is why it's this opinionated, and why it fits the blogs shaped like it unusually well.