Steven D. Brewer has been blogging since 2002: PHPWiki, then Drupal, then WordPress. With Drupal 7 at the end of its life he wanted a home for twenty-four years of posts that would need no maintenance, and put them on blog.sh: archive.bierfaristo.com, with the Drupal posts and the Twitter feed already in, and pieces of an old Esperanto-USA blog recovered from the Wayback Machine.

Worth a read if what you're after is an archive that has to outlive the software it was written in.

#blogsh #archive #drupal

Four squares on an A4

The leaflet is one sheet. Four panels — write, move, deploy, show — each with a terminal excerpt and a QR code. None of the codes lands on a page made for the event. Each one opens a tag page this site already had: /tag/authoring, /tag/migration, /tag/deploy, /tag/appearance. The site's own archive, sorted by what a stand gets asked, was the landing page. Nothing was built for the day that would be stale the day after.

The leaflet was older than the Czech

The leaflet went to print in mid-September, when a second language on this site was still a question rather than a setting. By the Saturday the question had been answered: 1.9 had shipped, this site had been bilingual for a fortnight, and every post it had published had Czech words. The leaflet had not been told. Its four codes still point at the English tag pages — a Czech leaflet, handed to Czech visitors, landing every one of them on an English page.

What stood between them and the Czech copy was the small chip in the banner's corner. Four of them found it. The other fifteen did not go looking, and for this crowd that is the expected number: LinuxDays is IT people and students, who read English all day and have little reason to switch. The mistake was real. Its cost, here, was close to nothing.

What the weekend was for

Nineteen people from the Czech Republic opened this site over those two days; the weekend before it was three. They stayed two and a half minutes on average and four out of five went past the first page. Sixteen came in at the front door, ten read the introduction, three opened the writing tag, two the migration tag, two appearance — and nobody opened deploy, which is a fair review of a leaflet panel. (The site counted 328 visitors that weekend. Three hundred of them were one crawler working through a search engine's index from Singapore. The number that matters is the small one.)

It came up several times at the table. Nobody's archive changed hands there, and nobody was expected to install a blog engine standing up. A stand is where a question gets asked out loud — would it carry my blog, does it write from a phone, where does it run — and the leaflet's four squares are those questions in the order they tend to come.

A project site at a stand is read on a phone, by someone who did not come for it, in whichever language they happen to think in. This time the site was ready for that and the paper was not — and almost nobody noticed, because almost nobody at LinuxDays needed the Czech. A stand where English is not a given would have noticed, and there the gap would have been exactly one QR code wide.

That's no longer the honest answer. Since 1.6, the build keeps a record of what went into each page, and remakes only the ones whose record no longer matches. The archive underneath is the same one this was measured on in August, seven posts heavier: 6,646 now, and the engine three releases on, at 1.9.

What you wait for today

Publishing a post dated today, on that same archive: sixteen seconds of build, two of upload — where it was forty-eight. The build isn't touching pages that didn't need it any more, so the size of the archive stopped being what the wait was made of.

Where the size still shows up

It hasn't disappeared. It moved. The record a build keeps depends on more than the posts — it hangs off a fingerprint of the engine itself: the templates, the code, the locales, the config. Change any of that, the way an engine upgrade routinely does, and the whole record is discarded at once. The next build after that is exactly the build this archive always had: every page, remade, because there's no way to know which ones the change actually touched without checking all of them.

Just now, on this same archive — 6,646 posts, 15,777 files — clearing that record and asking for a full rebuild took a minute and a quarter, start to a freshly deployed site. That's not a regression. It's the cost the archive has always had for the one operation that still has to look at everything; an ordinary day of writing just doesn't cause that operation any more. The rate underneath has barely moved either: divide that by the file count and it lands at about four and a half milliseconds a file, where August measured a little over four — the six per cent that 1.9 added to every cold build, because each page now asks which language it speaks, and nothing beyond it.

The practical consequence, updated

The advice from August still holds, and the gap it closes got bigger, not smaller. Bring an old archive in by importing it, not by writing it in post by post. The Mastodon import wrote 2,088 posts and rebuilt once, at the end — about the same minute and a quarter as above. One post at a time, even at today's flat sixteen-and-two per post, the same 2,088 posts would still cost something like ten hours of publishing for work a single import finishes before the kettle boils.

The limit was never the archive. It was rebuilding parts of it that already knew they hadn't changed.

The sixteen-and-two figure carries over from the measurement published alongside 1.6. The rebuild-from-a-cleared-cache figure is fresh — two timed runs against this archive on 1.9, seventy-five and seventy-one seconds, so treat "a minute and a quarter" as a first read rather than a settled number.

./blog.sh on Root.cz, the Czech Linux site, in Czech and in my own words: why the text and the pictures belong on your own disk, what a build is and where its result can live, how comments ride on the Fediverse, and why twenty-two importers read an export rather than an API. It also says plainly who the engine is not for: more than one author, anyone who wants a web admin, plugins.

Worth a read if you read Czech and want the whole case made in one place, including what the engine won't do.

#blogsh #rootcz #staticsite

On Saturday I will be at the stand of my friends from OSCloud all day. If you want to talk about ./blog.sh, ask how this or that works, find out whether it would carry your blog, or tell me what got in your way, this is the chance to do it face to face rather than in issues on GitHub.

Nothing much to prepare. A question is enough — or the blog you have been meaning to move. Everything else we will talk over at LinuxDays 2026.

Programme and directions: linuxdays.cz/2026

#blogsh #LinuxDays

Setting up

./setup.sh asks which language to speak first, and speaks it from the next screen on — the introduction used to stay in English above a Czech run, because it was said before the choice was made. While the site's name, short name, description, author and address are still the template's examples, Enter no longer takes them as answers: an address has to be yours, or http://localhost:8000 for trying things out on this machine. A deploy directory typed as ~/www is written out whole, and a prompt that shows nothing as you type now says what went in — its length and its last two characters, enough to tell an access token from the client key beside it and too little to give either away. A token pasted with a space on either side is trimmed before it is saved.

Esc does nothing

At "rebuild and deploy the site now?" Esc used to answer yes and deploy; at a post's crossroads it opened the editor; in a question you type into, it wrote an invisible control character into site.yml. Esc leaves without doing anything now, everywhere — in a typed question it is Esc and then Enter, because the terminal reads a whole line there. And q no longer closes a menu: it was a second Esc in the menus and nowhere else.

The command line

./blog.sh rebuild --help built and deployed the site, and rebuild --force — the rerun the deploy's own guard asks for — was taken for nothing. rebuild takes --full and --force and refuses anything else by name, and a rebuild whose build failed ends with 1. A mistyped command says it does not exist and names the nearest one, instead of scrolling the whole usage past.

A draft's properties

The properties screen shows where to read a draft, whole even at 80 columns, and [q] puts that address on a phone as a QR code — reading a draft on a phone used to mean opening it in the editor first. [p] asks before it publishes and announces. And the screen stopped promising an announcement nothing would send: on a site that announces nowhere, or has a network configured with its token still empty, it says so.

Surfer 7

Cloudron's Surfer 7 signs in with your Cloudron username and an app password, and no longer takes the access token every earlier Surfer did. SURFER_USERNAME and SURFER_PASSWORD go into env.sh; they can go in before the app updates, because an older Surfer is signed in to with the token until the day it is not. A refused sign-in stops the deploy at the first file and says which of the two was refused, instead of printing HTTP 401 once per file.

From the phone

Beside the single shortcut, the writing app sends its text from Chrome and Edge: Chromium shares only files whose extension is on its own list, .md is not on it, and the text was refused before any share sheet opened. It goes as .md.txt now, and the receiver puts the .md back. That one was found on an Android phone, by somebody who tested exactly what the browser refuses.

What doctor names now

A deploy backend whose program is not installed, rather than letting the first deploy find out after the build — and the rclone snap, which can read only inside your home directory. A quote left open in site.yml, by the line it opens on rather than the line where the parser gave up. A language file still holding the example's text, and one left behind by a language taken out of site.locales. An option it does not know: doctor --onlien used to run the offline checks and say nothing. It no longer ticks the site's identity while the author is still the example's, and no longer says the shipped banner will jump — only the ratio holds its space open.

Smaller things

A picture captioned in typographic quotes — ![alt](01.png „Caption“), what every phone keyboard writes — pointed at a file nobody has, and vanished from the page. Every embedded player drew a black rectangle on a host that sends a tight Referrer-Policy, which is Surfer's default. A file size used the English decimal point in every language. A podcast import put the show's cover over every episode. Ctrl+C left every screen of ./blog.sh through a stack trace. publish --json answered an unreadable date with prose and status 1, which a phone cannot tell from a crash.

The Czech interface

The engine's Czech said "post" in over 300 places, the help and the editor's hint included, while the sites it builds said "příspěvek"; a build was "postaven", constructed, where Czech puts one together — "sestavení". Now it says "příspěvek", "sestavení" and, for a draft, "koncept", in the wizard, the command line, the writing app and the Czech cheat sheet. The key is still d for "[d] nechat jako koncept". A script that reads the Czech output will see the new words.

A cold build costs about 6% more than 1.8's, the price of every page asking which language it is in. A cached rebuild costs what it did, so an ordinary day of publishing is unchanged.

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

Why there were two

A shortcut started from the share sheet runs in Shortcuts' background runner, whose only screen is a banner. Run Script over SSH needs a screen — the host prompt, the first-run privacy question — and is refused there with "This action could not be run with the current user interface", before any connection is made. The action that used to hand the run over to the full app is no longer offered. A shortcut started from a URL, on the other hand, always runs in the app. So the second shortcut existed only to be started from a URL.

One shortcut, run twice

It does not need to be a second shortcut. The same one runs twice, and tells the two runs apart by the one thing that differs between them: whether it was handed anything.

• From the share sheet, with the post's files as its input, it packs them into one batch, writes the batch to a file in iCloud Drive and opens a URL that names the shortcut itself.
• From that URL, with nothing handed to it, it reads the file back, sends it over SSH, deletes it, and opens the answer on the writing app's page.

A video on the way through is re-encoded to 720p — an iPhone clip of 32.5 MB came out at 5 MB — and a picture goes as it is.

Import it, then fill in what is yours

The shortcut is published signed, so anyone can import it: SendPost. What it cannot know is yours to fill in:

• in Run Script over SSH: the machine you log into, its SSH port, the user, and the path to scripts/receive.sh or the wrapper that reaches it — and a key, whose public half goes on the server;
• in the Text that builds the answer's address: your blog's address, base_url in config/site.yml.

It arrives called SendPost, and its last step opens itself by that name. Rename it and that step has to change with it; a name without spaces saves percent-encoding it.

One warning worth having before anything is edited by hand: Shortcuts reconnects a pasted action's inputs to whatever stands above the place it lands, so an action copied between shortcuts can come back reading from the wrong variable. Importing avoids that entirely.

And on a Mac

The same shortcut runs from Terminal: shortcuts run SendPost. Nothing on the server changed for it — only the phone's side got simpler.

The step-by-step, with a screenshot of the whole shortcut, is in operations.md.

Set up the remote once

rclone config asks its questions once and keeps the answers — the host, the user and the password live in rclone's own config, never in env.sh. Create a new remote, pick the type ftp, and give it the three things the hosting plan's welcome e-mail lists. Then two lines in env.sh:

export DEPLOY_BACKEND=rclone
export RCLONE_TARGET=myftp:public_html   # remote name : the directory the host serves

The part after the colon is whatever directory the host serves as your site — public_html, www, htdocs, depending on the host.

Why nothing else is needed

FTP cannot tell anybody what a file on the server contains; there is no checksum to ask for. A deploy that had to compare the server's copy with the build's would have to download everything first. It never has to: the engine keeps its own record of every file it has sent — the manifest, one per backend — and tells rclone exactly which files to send and which to delete. The first deploy uploads the whole site; every one after that only what changed.

Two things a shared host does

It may offer FTPS. Plain FTP sends the password in the clear. If the host supports FTPS, turn it on in rclone config (explicit_tls), and nothing in the engine changes.

It may allow only a few connections per account. rclone opens several at once by default, and a host with a low limit answers with "too many connections" halfway through the deploy. One more line makes rclone take them one at a time:

export RCLONE_ARGS="--checkers 1 --transfers 1"

rclone also has --ftp-concurrency, but its own documentation warns that it is very likely to deadlock unless it is set to one more than the two flags above together. The two flags are the simpler way to the same limit.

Before the first upload

./blog.sh doctor checks that rclone is installed — and that it is not the snap, which can read only inside your home directory and fails every deploy of a site kept anywhere else. ./blog.sh doctor --online then lists what already stands in public_html that the site does not put there: on a hosting plan that is usually the host's placeholder page or an old site, and the post Before the first deploy says what to do about it.

A deploy only removes what it wrote

A deploy writes the site's files, and deletes only files an earlier deploy of the same site put there. Everything else in the target stays, on purpose: the engine has no way of knowing whether a file it did not write is a leftover or something you need, and a deploy that guessed wrong once would be a deploy nobody trusts again.

That rule is right, and it has one sharp consequence. Most shared hosting serves index.php before index.html, so an old WordPress front page goes on answering at the root while the new index.html sits right beside it, unseen. An old .htaccess can keep rewriting addresses the new site depends on. The upload succeeded; the reader just never reaches it. (The git backend is the exception — every push replaces the whole branch, so nothing old survives there.)

Ask the target first

doctor --online reads the root of the deploy target and names everything in it the site does not put there:

$ ./blog.sh doctor --online
⚠️  The deploy target (/var/www/myblog) holds 5 item(s) in its root that this site does not put there: .htaccess, google1234abcd.html, index.php, wp-content/, wp-login.php.
   One of them is index.php, which a host serves before index.html -- an old front page can go on hiding the new one. A deploy never deletes what it did not write, so these stay and are served beside the site. Delete what you do not want by hand (FTP, the host's file manager); and name what is there on purpose under deploy.keep in config/site.yml, and doctor stops listing it (.well-known, where a host keeps its certificate challenge, is never listed).

It works the same way on every backend — Surfer through its API, a local directory by reading it, rsync, rclone and sftp by listing the directory — with one request and a deadline, so a host that does not answer is a warning rather than a hang. Run it once the target is set in env.sh and before anything is uploaded.

Clear it, and keep what is meant to stay

The clearing is yours to do, with whatever you used for the old site: an FTP client, the host's file manager. Leave what the host itself put there. .well-known/, where a host keeps its certificate challenge, is never listed in the first place.

Some things are there on purpose — a verification file a search console asked for, screenshots an old issue still links to. Name those under deploy.keep in config/site.yml:

deploy:
  keep:
    - google1234abcd.html

and the next run is quiet about them:

✅ The deploy target (/var/www/myblog) answers, and everything in its root is this site's.

Only doctor reads that list. A deploy never deletes what it did not write either way, so keep is a note to doctor, not a lock on the target.

The program behind the backend

Four of the six backends hand the upload to a program — rsync, rclone, sftp, git — and a machine without it used to find out from the first deploy, after the whole build had run. doctor asks now:

❌ The rsync backend runs rsync, and rsync is not installed here -- every deploy would fail after the build.
   Install rsync from your system's packages, then run ./blog.sh doctor again.

rclone has one trap of its own. Installed as a snap, it can read only inside your home directory, so a site kept in /srv fails every deploy on files that are plainly there. doctor names that too, and points at the distribution's package or rclone.org instead.

And do not point it too early

One more thing worth knowing before the target goes into env.sh: saving a draft builds and deploys the site, because a draft's preview is a real address on the real site. The first deploy is rarely the one you type by hand. An unedited env.sh deploys nowhere and everything else works — writing, previewing, importing — so the target can wait until the site is ready to be seen, and until doctor --online has had its look at what is already there.

One file per language

What the site says in Czech lives in config/site.cs.yml, beside the config. Start one from config/site.lang.yml.example — copy it, and its comments say the rest. It takes the same keys config/site.yml has for its words, written in the other language, and whatever it leaves out stands as site.yml has it. This site's own, trimmed:

# config/site.cs.yml
site:
  description: "Minimalistický blogovací engine, který ovládáš z terminálu …"
nav:
  - { label: "Vše", url: "/" }
  - { label: "Začni tady", url: "/posts/2026/blog-sh/" }
  - { label: "Proč", tag: "philosophy" }
about:
  heading: "O projektu"
footer:
  note_heading: "Licence"
  copyright: "Texty a obrázky © 2026 Daniel Šnor."
tags:
  philosophy: "filozofie"
  authoring: "psaní"

The title, the description, the banner's claim and its alt text, the about card, the footer and the menu: those are words, and they translate. The picture in the banner, the author, the address, the colours, the widgets' accounts are facts about the site, the same in every language, and there is no key for them here — translating a fact would make a second site.

Some headings translate themselves

"About" over the about card, "Links" and "Find me on" over the footer columns, and each widget's heading are the engine's own words when site.yml does not write them — and then every language says them in its own words, with nothing to translate. Write one in site.yml only to say something else, and translate that one. The wizards leave the engine's words out of site.yml for the same reason: frozen into the config, they would stay in one language.

A tag is an ID with a word per language

A post's tags are metadata, written once, like its date. So a tag keeps one ID in every language — one page per language at the same address, /cs/tag/philosophy/ — and only what a reader sees changes: the word on the pill, over the tag's page, in its feed, in the tag index and in what the search box finds. tags: gives each tag its word, keyed as the posts write it. A tag with no word shows as written, and a word for a tag no published post carries shows nowhere; check says so, and the build goes on.

The menu goes to the same places

The menu and the footer links are written out in full, the way site.yml has them — but every item goes where the same item goes in site.yml, in the same order. Only the label changes. A menu that drifts apart between languages is a second site, and a reader who switches language would lose the item they were reaching for. So the build refuses one that drifts, and says where:

❌ site.cs.yml: nav has to go to the same places as in config/site.yml, in the same order -- only the words change. Item 2: config/site.yml goes to tag:philosophy, site.cs.yml to tag:authoring.

The address in an item is still the one the site's own language writes. url: /posts/2026/blog-sh/ above leads to the Czech copy of that post in the Czech menu, whatever its Czech slug is — the item follows the piece, not the spelling. A tag: item leads to the tag's Czech listing, and the front page, the search and the archive to their Czech copies.

What stays in one language

The writing app is one copy for the whole site, and it speaks the site's own language, because that is the language its author writes in. And the rules are enforced rather than hoped for: a key the engine does not read is refused, so is a translation of something site.yml does not have — an about text only one language would show — and a language file that is not valid YAML stops the build, with check and doctor naming the line.

That is the whole of it: posts say their own words, and one file per language says the site's.

One post, a text per language

A post keeps everything that is true of it once: its date, its tags, its series, whether it is pinned, whether it is published. What changes with the language is the words — the title and the text — and those sit side by side inside the same post:

./blog.sh translate a-slug-is-an-address-not-a-name --lang cs

The editor opens with the title and the body and nothing else, because that is all a translation is. The post is still one post: publishing it publishes it in every language, and a tag added to it is added in every language. There is no way for the Czech copy to be a draft while the English one is live, or to be filed under a different tag.

Nothing has to be migrated to start. A post with no translation is simply a post in the site's own language — which is every post in every archive until the first translate.

Where each language lives

The site's own language keeps the root, and every other language gets a root of its own:

/posts/2026/a-slug-is-an-address-not-a-name/
/cs/posts/2026/slug-je-adresa-ne-jmeno/

The root does not move when a second language arrives, so every link anyone has ever made to the site goes on working. The Czech copy gets a Czech address — made from the Czech title the first time it is written, then left alone, the same way the post's own address is. Pictures, the stylesheet and the writing app exist once and are shared; the sitemap names every language and says which addresses are the same page in another.

When a translation is missing

A post nobody has translated yet is not hidden from the other language. It stays in the Czech listing, in English, and its link leads to the one copy it has — so the same words never stand at two addresses, and a reader browsing in Czech still sees everything the site has written.

On a site with three languages, what stands in for a missing one is yours to decide. One line in the language's own file says that German, when it has nothing, borrows the Czech text rather than the English — and the words and the link always come from the same answer, never Czech text under a link to the English page.

Switching

The switcher is a small chip in the banner's corner, next to the light/dark button, and it works the same way: a click moves to the next language, and wraps around at the end. Which language you read in is a choice about this visit, like which mode you read in, so it sits where that choice already lives — not in the menu, which it would break in two. From a post it leads to that post in the other language; where the post has no copy there, it leads to that language's front page instead of to a page that doesn't exist.

Knowing what is written where

With two languages, the question an archive raises is no longer only "what is broken" but "what is missing", and it gets its own report:

$ ./blog.sh check --languages
                                               en  cs
a-badge-that-says-what-a-post-is               ✅   ✅
a-bicycle-nobody-had-to-draw                   ✅   ✅
…
how-big-it-can-get                             ✅   ·
the-lock-that-doesn-t-wait                     ✅   ·
the-parts-that-don-t-rebuild-themselves        ✅   ·

That is this site, today: every published post in both languages, and three drafts that haven't gone out yet still waiting for their Czech words. A plain check doesn't count those as problems, because a post that exists in one language isn't wrong. Publishing is where it matters, so publish stops and names the languages a post has no words in, and offers --allow-partial in the same sentence for the times a post is meant to go out in one language only.

The title over the page, the menu and the footer have words of their own too, and they are translated in a file beside the site's config — that is a post of its own. What this one is about is the part that decides whether two languages stay one site: a single archive that knows, post by post, which words it has.

The release about publishing in more than one language. Name them in site.locales, and a post keeps one date, one set of tags and one series, with a text per language written by ./blog.sh translate. The site's own language keeps the root, every other one gets its own, and one rebuild makes all of them. The banner, menu, footer and tags speak each language too; a post nobody has translated still shows, linking to the one copy that exists. This very site has been running in English and Czech since the release was a draft.

Around it, the first hour: two people installed 1.9 from nothing and upgraded a copy of a 6,600-post site, doing only what the docs said, and everything they tripped over is fixed. Esc never does anything, the setup speaks your language from its first screen and will not take the template's example as your site's name, a draft's properties show where to read it — with a QR code for the phone — and doctor --online now asks the deploy target what stands in its root that the site does not put there.

One thing to do if you deploy to Cloudron's Surfer: Surfer 7 signs in with your Cloudron username and an app password instead of a token. Put them in SURFER_USERNAME and SURFER_PASSWORD; they can go in before the app updates, and the token carries on until it does. Otherwise nothing to migrate — git pull, rebuild, deploy. The first deploy sends every post page once, because every page now names its language. Full notes →

Most of an installation doesn't qualify. The engine itself is a git clone; pull it again and it's the same engine. Everything the build writes comes back with one rebuild, given what's left.

The instinct is to back up the site itself — the folder a browser actually sees. That's precisely the one thing this list leaves out. public.nosync, the build's own output, is exactly as disposable as the engine that made it: one rebuild reproduces it byte for byte, so keeping a copy of it would just be storing the same information twice, under two different names, and trusting the older copy by accident.

What's left, once the engine and the site it builds are both set aside, is a short list.

What's actually irreplaceable

The posts themselves, first — the one thing on this whole list that a rebuild, a re-clone or a redeploy cannot get back under any circumstance.

Beside them, and easy to leave out by accident: the version history each edit keeps. It sits next to the posts rather than inside them, so a backup of the posts alone keeps the archive and quietly loses the undo — the difference between a restored site and a restored site that can still answer "what did this say before I broke it."

The media is its own case since 1.6: a published picture is a hardlink back to the original file, not a second copy, so backing it up costs exactly what storing it once costs — even though the same picture may be referenced from a dozen places in the archive.

Then the smaller, easier-to-forget pieces: config/site.yml for the site's own identity and integrations, env.sh for the tokens that make it post anywhere at all, and the banner and favicon images — gitignored on purpose, which means a fresh clone hands back the engine's own defaults instead of yours, silently, if nothing kept a copy of the real ones.

Beyond that, only a couple of conveniences remain: the trash, in case a delete needs undoing later, and a hand-built palette, if the site's colours were ever anything other than what it shipped with. Neither is precious the way the rest of this list is.

What restoring actually is

A fresh clone, those few paths copied back, one rebuild. That's the whole procedure — and it's also, unchanged, what moving an installation to a different machine entirely looks like. A backup and a migration are the same short list, read on two different kinds of bad day.

Everything left off it — the build's own output, the deploy manifests, the build cache, the markers a scheduled publish leaves for itself between steps — either regenerates for free on the next run or costs exactly one operation to rebuild. None of it is a record of anything; all of it is a record of what the last run already knew how to redo.

Not a backup — an export

It's worth keeping the two apart, because they answer different questions. A backup is those paths exactly as they already are, meant to come back exact. An export converts — what markdown can't represent comes out as HTML instead — because it's built for leaving, not for returning. Restoring from an export works, but restoring from the archive itself is the one that loses nothing on the way. An export preserves the site. A backup preserves the project.

A deploy walking a tree that another run is still rewriting can serve a page half-written. A run pruning orphans can delete, as an orphan, a page the other run published a second earlier. Neither failure announces itself — the site just ends up quietly wrong.

The lock, and what it refuses to do

One file, .blog-sh.lock in the project root, stands between those two runs — and it makes a choice that looks wrong until you see the alternative. A run that finds the lock already held does not wait for it.

A cron tick that loses that race says so and leaves, exit 0. Cron doesn't need it to wait: the next tick is minutes away regardless, and the alternative — queuing behind the lock — has a worse failure mode than losing a turn. A pile of blocked runs all wake at once the moment the lock frees, and all try to do the same work together.

A run started by hand is held to a different promise. It reports the collision and exits non-zero, because the quiet alternative — succeeding at nothing while looking like it succeeded — would mean ./blog.sh told you a deploy happened when it didn't.

One operation, not three

Publishing on schedule is publish, rebuild and deploy back to back, and the lock is held for all of it at once rather than reacquired between steps — a rebuild starting the instant a publish ends is exactly the overlap the lock exists to prevent, just with itself as both sides. The build and the deploy it shells out to inherit that same lock instead of asking for their own, which is the difference between one run holding a door open for the parts of itself that come after, and that run deadlocking against its own child.

Where the choice doesn't even come up

Reordering the queue takes the same lock too, and it's the one place the pattern above breaks — worth naming rather than skating past. It never touches public.nosync; it writes the same post files a scheduled publish would read from, and it holds the lock for the instant of the move alone, the checks and the writes together and nothing longer, never while a prompt sits open waiting for you to pick a slot. There's no cron-versus-human choice to make here, because there's no interval to lose in the first place: an operation over before the next tick could possibly land doesn't need to decide between waiting and bailing. A queue screen left open overnight has never once kept a cron tick out — not because it was built to be polite about it, but because it was never open long enough to be in the way.

Where a filesystem can't do advisory locks at all — some network mounts — the lock quietly degrades to no lock, which is exactly where every installation stood before this existed.

The engine's own architecture notes put the rest of it plainly: the threat model is a static site with no server of its own. Nothing here listens on a port. The goal was never to harden a complex system against everything that could go wrong with it. The goal was to avoid needing one in the first place.

What's left to get wrong, once that's true, is narrower than a normal blog's list — what the pages carry, what the working directory holds, and the one thing that does arrive from outside.

The one thing that arrives from outside

Writing from a phone means one door does accept bytes from a stranger's own device: scripts/receive.sh, running as the forced command of an SSH key. It listens on nothing — no socket, no daemon, just a key that can run exactly this script and nothing else.

What comes in is a filename and a stream of bytes.

The filename is held to a short list of things it may not contain: no path inside it, no leading dot, no control character.

The stream is bounded before any of it lands — BLOGSH_MAX_MB cuts the read off first, so nothing gets to overflow anything downstream by simply being large.

And the markdown that follows is parsed confined: an image reference may only be a bare filename, because a path like /etc/passwd typed into ![]() would otherwise be read straight into the post and published as if it were a photo.

There's no archive format anywhere on that path, on purpose. Nothing here ever unzips what a stranger sent, which is also the reason there's nothing to zip-slip.

What the page itself can be tricked into showing

Every piece of text that came off a network — a Fediverse display name, an avatar address, the text of a reply — gets escaped twice, the same way both times: once when the build writes the HTML, again in the DOM a visitor's own browser builds live for the comments. The one exception is Mastodon's own status HTML, trusted because it was already sanitised by Mastodon before it reached here — the trust sits in that process, not in the content itself. Whatever a browser is allowed to run beyond that is named in a Content-Security-Policy delivered as a meta tag — because a plain static host may not let a site set a header at all — and a media provider's origin is admitted only on the pages that actually embed one; an archive page with nothing embedded permits nothing.

Limits, stated rather than implied

A draft's preview address carries a random token and a noindex, long enough that nobody stumbles onto it and hidden from search besides. That's obscurity, not a lock. Anyone the link reaches can read the draft — which is the entire point of being able to send someone a link — so it's worth calling that what it is rather than dressing it up as access control it was never meant to be.

env.sh holds the real credentials, stays out of git, and is written 600. The one place that quietly slips: the setup wizards leave a .bak of whatever they rewrote, at the same permissions, holding whatever tokens were live before. Worth deleting the moment a rotated token is actually confirmed rotated — a forgotten .bak is a second, unwatched copy of a secret you thought you'd retired.

And underneath both of those sits one thing this model doesn't defend against at all: the machine actually running the build. A compromised laptop or a compromised server has already won, the same way it would against any tool invoked from that machine's own shell — there's no scenario here where the build defends against its own operator, and no attempt to pretend otherwise.

None of this reads like a checklist bolted on after the fact. It reads like what's left over once a login, a plugin list and an upload endpoint that takes anything were never on the list to begin with.

Pavel moved a WordPress blog off a shared host and onto blog.sh, over plain FTP. The write-up goes step by step: the WXR export, the import, rclone, a dry run, the deploy.

Worth a read if your site lives on a host that gives you FTP and nothing else.

#blogsh #wordpress #staticsite

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 <body> 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.

A release about what happens when something goes wrong. Every page, feed and index is now written to a temporary file and renamed into place, so a save interrupted by a full volume or a build stopped mid-write no longer leaves a page at half its length, or a post at 0 bytes with the old text gone. A cold build costs about a fifth more for it; a cached rebuild does not, so an ordinary day of publishing costs exactly what it did.

Arriving twice stopped meaning happening twice: a post sent from the phone twice, or one receipt delivered in two copies at once, is one post now, and re-importing this engine's own export no longer turns 1200 posts into 2400. And an address is no longer trusted just because it looks like one — a ../ in a slug, a media filename or a redirect target stays inside the site, a local deploy stays inside its directory, and a feed's redirect cannot send a fetch to localhost.

Before the tag, five narrow review passes went through the write paths, the build's output, import and export, check and the series; everything they found is fixed and pinned by a test that fails on the old code. Most of it nobody will ever meet. What you might: check asks what the build asks, so a page slugged index.html no longer stops every build while check calls the archive sound; an export no longer stops at the first broken post, and comes home with its empty paragraphs and embeds intact; a series of twenty parts or more opens at part one; and a part numbered 08 no longer loses its number to octal.

Nothing to migrate — git pull, rebuild, deploy. The first build renders every page once; on my own 6,600-post archive the deploy after it uploaded a single file, the Markdown cheat sheet. Full notes →

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, your Cloudron username in SURFER_USERNAME and an app password in SURFER_PASSWORD, 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.

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.

It had been waiting for the index.

Why it sits at the end

An MP4 is a handful of boxes laid end to end. One of them, mdat, is the picture and the sound. Another, moov, is the index: which frame is at which byte, how long the thing runs, what codec to hand it to. A player needs moov before it can show a single frame.

A recorder cannot write moov until the recording stops: until then it does not know what will be in it. It writes the picture first and the index last. Every phone does this, and so does the share sheet that repacks what the phone recorded. The file is correct and it plays. It only makes the reader download all of it to see the first second.

Moving that index to the front is one flag of one program. What was missing was anything in the engine that knew the question existed.

Reading where it sits

lib/video_probe.rb walks the file's top-level boxes, reading the four-byte length and four-byte name of each and seeking past the body. No ffprobe, no gem -- the same box walk that already reads a video's frame size. If moov comes before mdat, the file starts fast. If it comes after, it does not.

A counter around File#read, on a forty-megabyte file with its index at the end: twenty-four bytes. Three box headers. The forty megabytes between them are never touched.

It answers nil, not false, when the question does not arise -- no moov, no mdat, nothing it can parse. "I cannot tell" and "badly ordered" are different answers, and running them together would report a fault about every unreadable file. The walk also refuses to descend: an mdat is full of bytes that can spell anything, including a box header spelling moov.

Moving it on the way in

media: remux_video: true in config/site.yml, and the engine repacks a video as it is attached:

ffmpeg -nostdin -loglevel error -y -i IN -c copy -movflags +faststart OUT

-c copy is the whole of it: the picture and the sound are copied across as bytes, nothing re-encoded, nothing decided about quality. +faststart writes the index first. A QuickTime .mov comes out .mp4 while it is there, because some browsers decline the container whatever is inside it. An .mp4 that gets repacked comes out 01-web.mp4 rather than 01.mp4: the same name is offered when an author runs ffmpeg by hand, and ffmpeg refuses its own input.

A repack counts as done only if ffmpeg left cleanly and left a file with bytes in it: a tool that dies halfway leaves a truncated file and can still exit happy, so the status alone is not an answer.

This was exercised against thirty real videos out of a working archive with ffmpeg 7.1. Three carried the index at the end. All thirty came out fast-start, and every one kept its duration, which is what proves the copy is a copy.

The ones already in the archive

check opens the videos an archive already holds and names the ones with the index at the end, by post and by file:

klip: the video 01.mp4 carries its index at the end of the file.

Beside each it prints the repack command -- in outline, with FILE where the name goes -- and the setting that does it on future saves. It is a warning, not an error: check leaves with zero and counts it worth a look rather than a problem. The file is not broken. It is slow, and slow is the author's to decide about.

On a save the same sentence appears only where the two older notices have nothing to say. An HEVC clip and a .mov already come with a command that moves the index as a side effect, and a third command for one file is a third thing to weigh.

What it refuses to do

It needs ffmpeg and does nothing without it. With the setting on and no ffmpeg on the machine, the save says the repack was skipped and stores the file as it arrived.

A repack that fails is not a refusal either. The post is saved, the video goes in as it came, and the author gets the sentence they would have had with the setting off. That is the difference from the HEIC conversion, which does refuse: a HEIC photo displays in Safari and nowhere else, while a video in the wrong wrapper still plays for nearly everybody.

check fixes nothing. It prints the command, and running it is a person's job.

It is off by default, like everything else here that shells out to a tool the engine does not ship.

What it costs

Installing ffmpeg once. On save, the time it takes to copy one file: the cost follows the size of the video, not the length of an encode that never happens. And nothing on the archive already on disk until the commands check hands over are typed, one video at a time.

1.7 puts fifty-five drawings in between, and gives each of them a name.

Fifty-five nouns

Counted in lib/icons.rb: the eight content types, fifty-five more, sixty-three names a tag may ask for. Grouped by what a blog turns out to be about.

• getting about — bike car train plane boat walk
• places and weather — map pin mountain tree sun cloud rain snow
• a day — coffee beer food wine clock calendar home heart star gift
• making things — pen brush camera film mic music book tools hammer
• machines — laptop phone code terminal server bug lock key
• living things — paw bird leaf flower
• ideas — bulb flag globe eye chart target rocket mail briefcase box

Plain English, and the word somebody reaches for first: bike, not bicycle. A footer link under social: can wear one too, where the network marks have nothing to offer: globe for somebody's other site.

Why they sit beside the eight

The same 24-unit grid, the same two-unit stroke, the same currentColor — the part that lets one drawing follow a light theme and a dark one without a second copy. All fifty-five carry round ends and round joins, because they are pictures of things rather than diagrams and a mitred corner on a two-unit stroke reads as a spike at twenty pixels. doctor holds a hand-written icon_svg to that same grid.

Where it turns up

Two places. The heading of the tag's own /tag/<name>/ listing, and the date badge of every post carrying that tag — where it replaces the content type's icon rather than joining it. A badge is a small tile with a date and one glyph; the only thing that ever adds a second is a pinned post, and a listing stacks ten badges under each other.

A tag is matched by its address rather than its spelling. Sci Fi in site.yml reaches posts tagged sci-fi and posts tagged sci_fi, because those are one page and therefore one tag.

The order in the list is the priority

tag_icons is a list, and the order in it decides. Most posts carry more than one tag, and the tag a post was given first is usually whatever an importer put there rather than a subject — so the first entry in the list that a post has is the one it wears, settled once instead of post by post. A post tagged sci-fi, coffee wears coffee if coffee stands higher, whatever order the post wrote them in.

Written as a mapping — kolo: bike indented underneath, the shape half of site.yml is in — it draws nothing, and it always did: until now with no warning from the build, and doctor calling the file sound. Both name the key now, and doctor counts it a problem and exits 1.

What it refuses to do

It is not a folder to drop drawings into. Everything under assets/ is copied onto the site wholesale, so a folder of fifty would publish fifty files to serve a site that uses two — and an icon is written into the page rather than fetched, so nothing would ever ask for them. The set is a Ruby hash for that reason.

The eight content names cannot grow without a content type behind them. And an icon_svg that is not a drawing at all — a filename, an address, an emoji — is refused rather than printed where the glyph goes; the tag falls back to what it would have had with no entry.

What it costs

A name the engine does not have draws nothing, and the build does not mention it: configure bicycle instead of bike and the site builds, exits zero, and every post that should have carried a bicycle keeps its content type's icon. doctor is what says so: it names the tag, the name it asked for, and prints all sixty-three, eight to a row — then exits zero itself, because a tag without a picture is not a broken site.

And the drawing goes into the page. The middling one is a shade over 250 bytes of markup, written out again for every badge that wears it: no request for it, and no way to have it once. The whole set comes to about fifteen kilobytes, and none of it reaches the site — only the drawings actually used.

Most of the drawings in that file are this project's own. Several are the shape any icon set converges on for an obvious thing — the pen, the spanner, the speech bubble on a chat post — and those are the same paths as Feather Icons, MIT licensed, copyright Cole Bemis. NOTICE says so and carries the licence, which is what a repository owes the people it borrowed from.

Until this release the honest answer was: in a paragraph, like any other link. The card such a post opens with existed as a block -- the importers make them, out of Tumblr and out of Bluesky -- but nothing anybody could type produced one. The writer that turns a post back into markdown had no syntax for it, so edit on a link post offered to drop the card, and add <file> could not make one at all. This project's own release posts stopped being link posts after 1.3 for that reason. The tool had changed; the intent had not.

Three lines in the header

---
tags: release
link: https://example.org/somebody-elses-article
link_title: The article by somebody else
link_description: What its own page says it is about.
---

Two things in this are wrong and one is worth stealing.

link: is the address the post is about. link_title: and link_description: are the words on the card. The card is drawn above the text rather than inside it: in the saved post it is the first block, ahead of the first sentence you wrote, and on the page it comes out as the paragraph before yours.

It is a header key rather than a line in the body because the card belongs to the post and not to a paragraph of it -- and because a paragraph that is only a link already means something else.

What the post is then called

A post with no title: of its own is named by the card. The heading becomes the card's title, and that heading is a link: it goes where the card goes, on the post's own page and in every listing. In a listing the date badge beside it is the way to the post itself. Below it the card does not say the same thing twice: the title has been lifted, so what is left is the description.

Two things stay yours. The post's address is still cut from your own opening words, not from the borrowed title. And the announcement, when the post goes out, carries the post's address rather than the other page's.

The type is derived, so nothing has to say type: link: a post that is a card and the words under it is filed as a link post and turns up under the site's own listing of them.

Give the post a title: and nothing is borrowed. Your heading stands, and the card renders in full underneath it -- its title, linked, with the description under it.

A paragraph that is only a link

It stays an ordinary link in ordinary text. A bare address on its own line is turned into a link and nothing more; a markdown link alone in a paragraph is a paragraph with a link in it.

That is a refusal, not an omission. If a lone link became a card, the two would be indistinguishable, and there would be no way left to write the first one -- the sentence that points at something on the way past.

What a card's address may be

A whole http:// or https:// address, or one rooted at this site -- /posts/2026/some-post/ -- for a card about another post here. The second shape is not a convenience. check --repair writes it when it straightens a relative link left behind by an import, and a value the engine writes has to be a value it reads back.

Everything else is refused before anything is written: a bare filename, a scheme that runs, and the two spellings that read as this site and resolve elsewhere, //host/path and /\host/path. A card is the one link on a post that may carry no words of its own to be judged by. link_title: with no link: behind it is refused too, rather than guessed at -- words about a card with no card.

check verifies a card rooted at this site against the archive: point one at a post that is not there and it says so by name and leaves non-zero. An address out on the web is only reached with --online.

What it costs

The card is header text, which means a desk: add <file>, or the editor that add and edit open, whose guide lists the key. The page at /write/ has no field for it -- a post written on a phone is written without a card.

Nothing goes and reads the other page. The title and the description are the ones you type -- two lines of copying, and they are plain text: markdown inside them stays on the page as the characters you wrote.

And the card goes the way a header line goes. Take the link: line out on a save and the card leaves the post, with nothing said: the save's loss guard counts the blocks under the header, and the card is no longer one of them. A card further down a post -- one an importer left there, which markdown still cannot write -- is guarded as it always was. The one in the header is a line to put back, and no warning that it is gone.

Getting to that word meant opening the article.

That is what edit does. It reads the post out of its file, writes the whole thing back out as markdown, opens it in an editor, and parses what comes back. For a post that is paragraphs and photographs the round trip is faithful and nothing is at stake. For a post carrying something markdown has no form for, it is not.

Seven rows

props <slug> gains [e] -- on a draft, on a scheduled post and on a published one alike.

Properties of part-three -- what the post is, not what it says:

  1) series          (none)
  2) part of series  (none)
  3) tags            spring
  4) type            text (from the content)
  5) unlisted        no
  6) lead image      (the site's own)
  7) chapter list    (the site's own)

Two rows are pickers rather than prompts. The series row lists the series the site already has, each with the number of posts carrying it, and drafts count -- a series that so far exists on one unpublished post is offered too. It is a list because a series typed a second time is a second series; the last row is a field, for one the site does not have yet. check reports two names a few characters apart, but only after the parts are split between them. The type row lists the eight the engine ranks -- document, video, audio, image, chat, quote, link, text -- with the way back to letting the content decide above them, saying which type that is.

The tags row is a field, because a line of commas is how tags are written everywhere else here. Above it the screen prints up to fifteen of the site's most-used, and it reads the answer exactly as the front matter reads it: commas split, a leading hash off, brackets off, empties dropped. [release, foto] typed into that row is two tags, not two tags wearing punctuation.

What the screen is for

The same post, the same change, two ways. The post has a link card at the top and one small span inside a paragraph. The change is its tags.

edit stops before saving:

Careful, saving this would lose: 1x small span.
Really continue? Type "yes":

Anything but that word cancels the save entirely. A small span is a formatting run markdown cannot write, so the round trip hands back the words without it -- and no block changes type on the way, which is why the guard counts spans as well as blocks.

[e] changes the tags, leaves the post's content identical and asks nothing, because nothing is owed. The screen reads the file, replaces one key, writes the file back. Nothing is converted in between.

Three states, not two

unlisted is a yes or a no. The other two are not.

A post that says nothing about a lead image is not a post saying no to one. It takes layout.hero from site.yml. A post that says nothing about a chapter list takes the engine's own rule: the list appears by itself from four headings up. So those rows read yes, no, or (the site's own), and the third has to be reachable: choosing the row a third time lifts the key back out of the file rather than leaving a false behind.

What it refuses

A part number without a series. It says so instead of storing a field nothing reads. Clearing the series takes the part number with it, so a post rejoining a series later does not arrive with a position from a different one.

A number outside 1 to 9999. A 0 above all: a series has a first part and no zeroth one, and the build clamps a 0 to the front, so the screen would have printed "part 0" about a post every page of the site calls part 1. An answer it cannot use changes nothing and leaves the row showing what the post still carries.

The title, the date and the text. Those are the post rather than facts about it, and they remain the editor's business. The slug has its own key on the frame above, and on a published post so does the pin.

What it costs

A rebuild, once. Setting a series and choosing a type are two answers to one question, so the rebuild is offered when the screen is left, not after each row -- and a series or a tag is not one page, it is listings.

And it can refuse to save. The screen sits at a prompt for as long as somebody takes to answer, and the scheduled-publish cron runs every fifteen minutes. If the file changed underneath, the write is abandoned and says so, rather than putting a post the cron has just published back to a draft.

1.6 asked for that decision at the wrong end: publish at the moment of sending, before the blog has rendered anything, or see the blog's own page and then find a keyboard. 1.7 closes that, and then closes the road the answer takes back.

One file, down the same connection

The answer card for a draft now carries a Publish button. Pressing it sends one file, called publish.txt, holding the slug and nothing else -- through the same share sheet, the same two shortcuts, the same SSH connection the post itself took.

The receiver knows that shape: one file in the delivery, called that. It stores nothing. It reads the slug and runs publish <slug> --yes --json. The slug becomes an argument to a command, so it is checked as hard as a filename is -- lower-case letters, digits and dashes, no leading dash to be read as a flag, no newline in the middle to glue two lines into one word -- and anything else is refused here rather than explained by whatever it hits. A publish.txt arriving beside a markdown file is not a request; it is stored like any other file.

publish --yes --json answers as one object -- slug, path, state, url, deploy, warnings, the shape add --json prints -- and leaves with zero whatever it says, because iOS Shortcuts throws away the output of a remote command that failed. Press the button twice and the second press is answered rather than obeyed: already_published, with the address.

An answer the page goes and gets

The road back has one break in it that nothing on the server can mend. The reply travels as a URL, and a page kept on a phone's home screen runs with storage of its own: the URL opens in the browser, where the draft it is about does not exist. The draft stays on the home-screen copy, looking unsent. A phone that goes into a lift loses the same answer for a duller reason.

So the page stops waiting. Before it sends anything it picks a name for its answer -- sixteen hexadecimal characters out of the browser's random source, a fresh one for each send -- and writes it into the post as receipt:. The build then leaves a small file at /write/r/<name>.json. Here is one, whole:

{"slug":"on-the-tram","state":"draft","title":"On the tram","url":"https://example.com/draft/41a0a9b77caef98a/on-the-tram/","warnings":[]}

The page asks for that address every three seconds for five minutes, and says so if it never comes: a page that gave up in silence would be indistinguishable from a post that never arrived. Press Publish and it asks the same name again until the state says published.

The build writes it, which is what keeps it true: publishing the post rewrites the same file, the draft's preview address giving way to the public one; deleting the post stops it being generated and the sweep takes it away. An answer arriving is itself the proof that the build and the upload went through.

What is in it, and what is not

Five things: the slug, the state, the title, the address, and whatever the save had to complain about -- a picture whose size could not be read, a video that will make the reader wait. The phone is the one place with no terminal to read those in.

Nothing else, on purpose. Not the path the post has on the server. Not what the run said about the site rather than about the post -- a missing base_url, whatever the rebuild warned about -- because the file sits at a public address and its only protection is that its name is sixteen random characters. Anyone who has them can read it. The draft preview it names is the address the draft is readable at anyway.

What it still refuses to do

Anything about a post already on the blog. The page cannot open one, edit one, delete, rename, schedule, or take a published post back down. It writes one post, sends it, and offers to publish that one -- and only that one, because publishing takes the receipt this page minted. It is the 1.6 design with one step added, not a console growing on the site.

What it costs

Pressing Publish announces. It is the road publish takes at a desk -- the date settled, the post out on whatever networks the site has configured, the site rebuilt and deployed -- and there is no undo on the phone.

The five minutes run from the send, not from the reload: a page reopened an hour later does not resume asking. And on a site whose deploy is owed to the next scheduled run, the file on the server can be older than the page's patience. The page then says there is no answer yet, that the blog may still be building, and to go and look before sending again -- which is not the same sentence as "it failed", and usually it was not.

Where the page is

It runs on this site, at /write/. It is a demonstration, and it keeps nothing: what you type stays in your own browser, and sending needs a key that lives in a shortcut on the phone of whoever runs the blog. Open it, write in it, and nothing here moves.

Beside it, the other half of the same idea — changing what a post is without opening what it says: its series, its tags, its type and three flags, from a screen. Then a link card written in the front matter, about fifty drawings a tag can wear, a video repacked on the way in so the reader does not wait for the whole file, and seventeen fixes.

#blogsh #ruby #staticsite

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.

1.6 lets a tag carry an icon instead.

tag_icons:
  - tag: "build"
    icon_svg: '<svg viewBox="0 0 24 24" …>…</svg>'
  - tag: "comments"
    icon: "chat"

It replaces rather than adds

On a post's date badge the tag's icon takes the place of the content-type icon; in the heading of /tag/<name>/ it takes the place of the generic tag icon. That was the requester's first point, and the one worth asking about rather than guessing: two icons side by side on a 60-pixel badge is not a badge, it is a puzzle. A tag with no entry changes nothing, so the generic icon is still there for everything you have not named.

The order is the priority

Most posts carry more than one tag — 68% of them on the archive this was measured against — so tag_icons is a list, and the first entry a post matches is the one it wears. That rule was chosen because the tag a post was given first is usually an importer's rather than a subject: twitter alone opens 1,256 posts on that archive. The order in your config is your order, not the post's.

Eight by name, or your own

icon names one of the eight the engine ships — text, quote, chat, image, video, audio, link, document. icon_svg is yours: drawn on the same 24-unit grid, stroked in currentColor so it follows the light and dark themes, with scripts, styles and event handlers stripped before it reaches a page. doctor checks every entry: whether the name is one the engine has, whether a hand-written SVG contains an <svg> at all, and whether it is drawn to the same scale as the rest. An unknown name used to draw an empty space and say nothing.

On this site, since today

The seven tags in this site's menu have icons now — a bulb for Why, a pen for Writing, a box for Archive, a spanner for Engine, the engine's own chat icon for Comments, an eye for Looks, a package for Releases. Look at the badge on the left of this post, then at the badges on the front page, and you will see the rule at work: a post tagged appearance, content wears the eye, because appearance is named and content is not.

The whole thing was asked for by one person, shaped by his three points, and shipped with the request still open so he could say where it was wrong. He did not have to.

share:
  - mastodon
  - bluesky
  - email
  - copy
  - system

What is prefilled, and what is not

The post's name and its address, where the target takes both. Facebook and LinkedIn take the address alone and read the name off the page. The reader writes the part that is theirs. bluesky, email, facebook, linkedin, threads and x are plain links, one address each, no script behind them.

Three that are not links

The fediverse has as many addresses as it has instances, and a page cannot know which one is the reader's. So mastodon is a button that asks — in a row that opens under the controls, in the site's own type — and remembers the answer in that browser afterwards. Nothing about the reader leaves the page; the instance name is kept where they typed it.

copy puts the address on the clipboard. system hands the post to the operating system's own share sheet, which on a phone is Signal and WhatsApp and Telegram at once, and on a desk is whatever the system offers.

Those three appear only where they can work. A browser without a clipboard API gets no copy button, a desk without a share sheet gets no system button, and a block left with nothing to draw hides itself rather than standing a heading over an empty row.

Why there is no Pixelfed

Pixelfed has no address a page can hand a post to. A button that opened nothing would be worse than none, so there is none, and the changelog says so under "not fixed, on purpose" rather than leaving you to wonder.

One new file

assets/js/share.js is a file every page now loads. On a site that never sets share: it does nothing at all; it is still a file, and a deploy that misses it leaves a 404 in the console. git pull, rebuild, deploy — and it is there.

The controls make no request to anyone until the reader presses one. That is the rule for everything the engine puts on a page, and this row is no exception: the share buttons of the web are usually the one thing on a page that phones home before you touch them, and these do not.

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.