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.

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.

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.

./blog.sh add post.md

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

Where the wizard would ask, this refuses

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

--json: one object, nothing else

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

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

Draft, unless the file says otherwise

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

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

--untrusted

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

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

Here you paste the address you would send a friend.

Two of them, actually playing

A video, with a caption:

Audio, the same gesture:

Two lines of markdown. No embed dialog, no account, no copied code.

What the post actually stores

Not their HTML. A provider, the identifying part of the address, and — because PeerTube is federated and has no single home — which instance it came from:

"type": "video",
"provider": "peertube",
"url": "https://framatube.org/w/kkGMgK9ZtnKfYAgnEtQxbv",
"embed_id": "kkGMgK9ZtnKfYAgnEtQxbv",
"embed_origin": "https://framatube.org"

The build assembles the player from that. Two things follow. No foreign markup ever enters your archive, so nothing arrives carrying its own tracking. And when a platform moves its embed path, the fix is one edit in the engine, not a re-import of fifteen years of posts.

The page's own policy follows the same rule. Beyond YouTube's two origins, which are granted everywhere because an imported embed can point at either of them, a page allows only what its own posts play. This one names framatube.org and w.soundcloud.com — and so does whichever listing page happens to be showing it, because a listing is made of the posts on it. A page with no player in it names neither. A blog with no Spotify in it never mentions Spotify.

Being straight about the limit: the player is still an iframe served by the platform, and the moment a reader presses play, the platform knows. What changes is that your archive doesn't carry their code, and the rest of your site doesn't reach for them at all. (YouTube players are built on youtube-nocookie.com, which at least holds the cookies until playback.)

Video, audio, and two that have to be asked

Video: YouTube, Vimeo, PeerTube, archive.org. Audio: Spotify, SoundCloud, Mixcloud. Every one of those is a string transform, so writing a post stays an offline operation.

Funkwhale and Bandcamp couldn't be. Funkwhale's obvious embed path builds a player that looks entirely correct and stays a black rectangle forever; Bandcamp's address contains no id at all, only a slug. Both are asked once, when the post is saved — the only moment writing needs the network — and the answer is stored as an address, so an edit never asks again and the build stays offline. If the lookup fails, you get a sentence and a saved post with a link in it. Never a refused save: writing on a train has to end with a written post.

The rules came from the services, not from their docs

Every pattern here carries a correction that no documentation page would have given us. An unlisted Vimeo link needs its hash or the player answers 403. A Spotify address copied out of a browser carries an intl-xx segment the embed path rejects. SoundCloud has no id to extract at all, so the whole address goes to the widget — which is also how a private track's secret token reaches it. Mixcloud's widget redirects to a second hostname, and the page's policy has to allow that one too.

PeerTube is the awkward one, and instructive. Being federated, it has no domain to match against: the shape of the path is the entire signal — a full UUID, or the 22-character short id PeerTube derives from one. Which means a 22-character slug sitting on some other site's /w/ page would be taken for a video as well. That is the residual cost of a platform with no home address, and it fails where you can see it — an empty player, one edit away from being a link again — rather than quietly.

And when an address says nothing the engine recognises, nothing is guessed at. The post keeps the link, and the page says the video is unavailable, politely, instead of drawing an empty frame and hoping.

Now the previous text is kept before every overwrite, and [v] in a post's properties puts one back.

Before every overwrite, not just before an edit

A re-import is an overwrite too, and that turns out to be the case where this earns its keep. Editing a post by hand is deliberate; re-importing a source over a post you have since tidied up is the accident that eats an evening's work, and up to now the only recovery was a backup.

Ten per post, newest first.

Picked by recognising it, not by reading a timestamp

The list is one you walk like every other list in the wizard, and the row under the cursor shows what that version said — its title, or its opening words if it hasn't got one. Ten timestamps tell you nothing about which one is the version you want. Ten opening sentences tell you immediately.

Confirming is one keypress, and it can be that cheap because restoring loses nothing: the current text is kept as a version of its own before it is replaced. A wrong choice is one [v] away from being walked back.

What it doesn't cover

Text only. Images are not versioned, and the line above the list says so rather than leaving you to find out. A restore brings back words, and the pictures are whatever the post's media directory holds now.

Ten. The eleventh save pushes the oldest one out. That is a decision about disk rather than about safety — but it did produce a bug worth naming: ten re-imports that changed nothing used to fill all ten slots, quietly pushing out the hand-edited state the versions exist to protect. A version identical to the newest one stored is no longer written.

A save always wins. If the versions directory cannot be written — a full disk, the wrong permissions — the copy is skipped and the save goes through anyway, silently. That is deliberate and I would choose it again: the point of this is to lose less, and refusing somebody's save because the undo could not be filed would lose more. It does mean the undo is a courtesy rather than a guarantee, which is the difference between it and a backup.

They live with the content. content.nosync/versions/, beside the posts. They travel with a post into the trash and back out again, and a restore from a backup that copied only posts/ brings back the archive and loses the undo. The backup list in the docs says which paths matter; this is a new line on it.

The key appears when there is something to restore

A post that has never been edited shows no [v], because an undo with nothing behind it is a key that teaches you not to trust the keys.

./blog.sh browse shows the same posts list does, as a screen you stay in.

What it is

Arrows and Page Up/Down through the whole archive. Filters by type, state and tag, with the count next to each. And a search that filters as you type.

The search is the site's own. Words are ANDed, "a quoted phrase" counts as one, -word excludes, and diacritics never decide a match. The query language and the folding live in lib/search_query.rb, next to a note that it and assets/js/search.js change together — because a query that means one thing in your browser and another in your terminal is worse than having no search in the terminal at all.

It searches the full text of every post, so under the selected row there is a line of that post's own text showing you why it matched.

Space opens a read-only preview — the same markdown edit would hand you, with media lines shortened to their filenames. Enter opens it for editing and comes back to the same row, with the same filter still applied. z clears the filters.

Two small decisions that took the longest

The keys are deliberately none of the letters that mean an action elsewhere. p is "publish" in three dialogs and x is "delete" in two, so neither could be the preview key here — muscle memory does not check which screen you are on. The preview is the space bar, the way every file manager has done it for thirty years.

The rows lead with the title, not the slug. list still prints the slug first, because down a pipe the slug is the thing you copy into the next command — and browse falls back to exactly that when it is not talking to a terminal. But on screen, a title is what you are scanning for. On an imported archive that matters more than it sounds: over half the posts arrive with no title at all, so the row falls back to the slug for those, which is precisely the set where the slug is all there is.

Who this is actually for

Twenty-two importers mean archives that are thousands of posts long, not dozens. list was written when this site had fourteen. Scrolling a pipe is fine for fourteen.

For four thousand imported posts, from six platforms, half of them untitled, you need to be able to look — filter to one origin tag, search for a word you half remember, read the matching line, open the one you meant. That is the whole feature, and it only became necessary because the importing worked.

Social networks strip that on upload. They have done it for years, quietly enough that most people have stopped thinking about it. A static site has nobody to do it: blog.sh copied your photo into the archive byte for byte, and nothing in the engine had ever looked at metadata at all. So a picture of a cat on a windowsill published the windowsill.

From 1.2.1 it doesn't. A photo loses its location on the way into the archive — when you add it to a post, and equally when it arrives through any of the twenty-two importers, because they all end up in the same write.

Only the location

The camera, the lens, the exposure, the moment the shutter opened: those stay. They are your own record of your own photograph, and an archive that silently threw them away would be answering a question nobody asked.

One tag matters more than the rest, and it stays too: Orientation. A phone held upright stores the picture sideways and writes down that it should be turned. Delete that tag and every portrait photo on your site lies on its back. Turning the pixels themselves would need an image decoder, and blog.sh runs on the Ruby standard library and nothing else — no gems, by design. Keeping the one tag that matters is what makes this possible without a dependency.

If your site is the kind that wants the place kept — a walking diary, a photo blog where the map is the point — one line turns it off:

media:
  strip_location: false

The photos you already published

Those are left alone. An engine upgrade should not go back and rewrite pictures you put on the web years ago, so nothing happens until you ask.

Ask first what there is to ask about:

./blog.sh doctor

It counts the published photos that still carry a location and says so in one line among the rest of the checkup. If the answer is none, you're done.

If it isn't, this cleans them:

./blog.sh doctor --strip-location

That is the only thing doctor has ever written rather than reported, which is why it has to be asked for by name. It prints how many it changed, and one thing worth knowing before you run it: every rewritten photo gets a new checksum, so your next deploy uploads all of them again. On a big archive that's a real transfer, not a rounding error. Then rebuild as usual:

./blog.sh rebuild

What this doesn't cover

Written down rather than left to be discovered, because a privacy feature that quietly misses cases is worse than one whose edges you know:

• JPEG only. That's what phones produce, and a HEIC converted by the engine arrives as one. Exif in a PNG or a WebP is left alone.
• XMP isn't read. A file can carry a second copy of the coordinates in an XMP packet, and that copy stays.
• A GPS block holding nothing but its own version number isn't treated as a location, and the file isn't rewritten for it. This is more common than it sounds: in one real 2962-photo archive, three photos had exactly that shape — and not one of them had actual coordinates. Counting those would have been a headline made entirely of false alarms.

./setup.sh asks instead, and checks every answer as it arrives.

The questions that were quietly dangerous

Three settings could be typed wrong in a way nothing would ever tell you about.

The timezone. A typo here does not fail — Ruby falls back to UTC and says nothing — it just dates every post two hours off, forever. The wizard offers the zone from the machine's own database, unless the machine sits on UTC, which is a fact about a datacenter rather than about the person answering; then it suggests from the language you are being asked in. And it refuses anything that isn't a real zone.

The address. It lives in two places, and env.sh overrides config/site.yml. The shipped example has it pointing at example.com, so filling in only the config leaves your site calling itself example.com in its feed, its sitemap and every share preview. The wizard writes both.

The Mastodon account id. The sidebar widget wants a numeric id and people fill in an @handle, after which it shows nothing at all, quietly. The wizard verifies your token against the instance on the spot — and the id comes back out of that same call, so it can simply be offered, already correct.

Choosing one comments network switches the other off, because a config with both is one the build refuses to load.

Nothing is written until the end

Answers are collected, then both files' diffs are shown with secrets masked, and one confirmation covers the lot. Ctrl-C anywhere leaves an existing install exactly as it was.

Every question can be skipped with Enter. Re-running the wizard is how you change any of this later — and editing the files by hand keeps working exactly as it did. The two are interchangeable in both directions, because a config file you are not allowed to open is not a config file.

The diff shown is a proper LCS diff, incidentally. Comparing line for line failed in a way that mattered: adding one entry to a list shifts every line below it, so a four-line change read as everything from here to the end of the file — precisely the impression a tool asking permission to edit your config must not give.

And your comments survive

Both wizards write through a text-level editor that substitutes values into the documented template and leaves every other byte alone. Loading the YAML and dumping it back would have thrown away the two hundred lines of explanation, the commented-out blocks you uncomment when you want a widget, and the folded scalars real sites keep HTML in.

Every write is read back and verified, and restored from its backup if the file does not say what it was asked to say.

The four-line start

git clone https://github.com/DanielSnor/blog.sh.git
cd blog.sh && ./setup.sh
./blog.sh add
./blog.sh preview

The second line used to be two file copies and an editor. That is the whole change, and it is the one I should have made first.

That's not a paradox, it's an admission: eight of those ten were not activities. They were operations on a post, wearing the costume of a menu item.

Everything about a post, in one place

./blog.sh props <slug> — or, in the wizard, pick a post and press v — shows what there is to know about it. State, type, tags, whether it's pinned, whether it's been announced and where. If it's scheduled, the whole publishing queue.

And the actions live there too, next to the facts they act on. A draft offers publish and schedule. A published post offers unpublish, re-announce, pin or unpin, rename, delete.

You no longer go to a menu, choose "unpublish", and then hunt for the post. You go to the post and see that unpublishing is one of the things it can do right now.

What stayed where it was

Type and tags are still edited in the frontmatter of edit, prefilled with their current values, because they're text you write. The pin is a switch rather than a value, so it toggles right in the dialog with c — and the header line keeps working, for anyone who'd rather type it.

The five that remain are the ones that really are activities: write, edit, import, list, rebuild.

One guard worth mentioning

The dialog acts on the post it read when it opened. If the scheduled-publish cron fired in between — you opened the properties of a draft, went for coffee, came back at 09:31 — an action taken on that stale copy could have reverted a post the cron had just published, dropping its announcement URL along the way.

edit already guarded against exactly that. Now the dialog's actions do too. It's the kind of bug you only find by asking "what if something else touched this file while I was looking at it?", which is a question worth asking of every screen that holds state open.

If you script

The wizard's numbering changed with the shorter menu, so a scripted printf "4\n" | ./blog.sh picks something different than it did in 1.0. The CLI commands are the stable interface — none of them changed, and none of them will.

The old behaviour was the worst possible one: the file went in, the build couldn't measure it, and the image quietly vanished from the page — taking its caption with it. No error. Just a post with a hole where a photo was.

Refused, with the command you need

Attaching a HEIC now stops the save and prints the exact conversion command for the machine you're standing at:

sips -s format jpeg photo.heic --out photo.jpg      # macOS
heif-convert photo.heic photo.jpg                    # Linux

Your file stays exactly where it was, in incoming/. Nothing is deleted, nothing is guessed at. You convert it and carry on.

Or converted, if you ask

Set media.convert_heic: true and the engine converts it for you, using whichever tool it finds — sips, heif-convert, magick, vips. If it finds none, it falls back to the refusal above rather than pretending.

That's off by default on purpose. Converting means the file on your site isn't the file you handed over, and that should be a decision you made, not a thing that happened to you.

Detection is by content

Renaming photo.heic to photo.jpg doesn't get it past the check — the engine reads what the file actually is, not what it's called. Phones and export tools mislabel files often enough that trusting the extension would just move the silent failure somewhere less obvious.

The rule underneath

An image must never disappear quietly. If the engine can't handle a file, it says so, names the file, and leaves it where it is. A build that drops a photo and finishes with a cheerful summary has lied to you, and you'll find out months later when someone mentions the empty space.

(If you'd rather sidestep all of this: Settings → Camera → Formats → Most Compatible makes the phone shoot JPEG.)

So a site can now say when it usually publishes:

publishing:
  slots:
    - "mon 09:30"
    - "wed 09:30"
    - "fri 09:30"

Or, if you write more than that, a single "daily 09:00".

With that in the config, scheduling a draft offers you the next slot no other scheduled post already occupies. Three drafts written in one evening are offered Monday, Wednesday and Friday, in that order, without you counting days.

It only ever offers

This is the part I care about most, because a queue that takes decisions away from you is a queue you fight.

Typing a date overrides the offer, always. A post you hand-schedule for 14:17 on a Tuesday blocks nobody — it isn't in a slot, so the queue routes around it. And nothing ever moves a post that already has a time. The slots suggest; you decide.

Without the key in your config, the prompt is exactly the one that was there in 1.0.

The offer explains itself

An offer of Sunday, on a site with a Saturday slot, reads like a queue that skips Saturdays. So the offer names the slots it walked past and who is holding them:

next free slot: Sun 09:30
  Sat 09:30 taken by "the-post-that-stays"

A scheduled draft's properties print the whole queue for the same reason. A queue you can't see is a queue you don't trust.

The unglamorous half

Two drafts landing in the same slot would be worse than no queue at all, so the slot search skips anything already claimed — and it does that across a daylight-saving change too, which is where the first version double-booked. Clocks that move an hour twice a year are the reason scheduling code is never as short as it looks.

![A view from the window](window.jpg)

So a file attached to a post is the same line without the exclamation mark:

[Reading notes, 2025](reading-notes.pdf)

A whole line that is nothing but a link, pointing at a bare filename with a known extension, is an attachment. It gets staged through incoming/ like a photo, stored next to the post like a photo, and it never leaves your site.

A line with a URL in it stays what it has always been: a link. The difference is the bare filename — the same rule photos already follow, so there's nothing new to learn.

Rendered as a card, not a link

An attachment renders as a card carrying the label, the extension and the size. The size is there because a download deserves to say what it costs before you commit to it — a 40 MB PDF on a phone on mobile data is a different proposition from a 200 kB one, and the reader should get to make that call.

Over about 50 MB you get a warning when you save. Not a refusal — sometimes a big file is exactly the point — just a note that you're about to ask a lot of somebody.

The extensions that count: .pdf, .zip, .tgz, .epub, .txt, .md, .ics, .gpx, .csv. A whitelist, because the engine should only publish files it can honestly describe.

And a new kind of post

A short line plus a file makes the post a document — the same way a short caption plus a photo makes an image post. Write more than a caption and it's an article that happens to have an attachment.

The first document you publish makes DOCUMENTS appear in the navigation. Nothing to configure: the menu has shown only the types a site actually has since 1.0, so the section arrives with its first tenant and would leave with its last.

Publish and forget. That was the whole brief: a PDF, a GPX track, a calendar file — things worth putting somewhere permanent without writing an essay around them.

This post has one

Everything on this site, twenty-one chapters, in a single file — set in the two typefaces the engine bundles and coloured with its seven palette keys, because a document about a blog engine may as well look like the blog.

That card is the feature. Label, extension, size — and a file that lives here, next to the post, rather than at an address that might stop answering one day.

So pinned: true in a published post's header now holds a copy of it at the top of the first listing page. That's the whole feature, and the interesting part is everywhere it deliberately doesn't apply.

Only the front page

Type listings, tag listings, the RSS feed and the sitemap stay strictly chronological. A pin is a claim about what a visitor should read first, not a rewrite of when things were written. Someone subscribed to the feed gets posts in the order they happened, and a pinned post doesn't jump their queue every time it's toggled.

What happens as it ages

While the post is still recent enough to sit on page 1 by date, it appears exactly once — pinning it doesn't print it twice on the same screen. Once it has aged onto page 2, it appears in both places: at the top of page 1, and in its own chronological spot on page 2.

That second half is the part I'd have got wrong if I hadn't thought about the archive. A pinned post that vanished from its own date would leave a hole in the record, and the record is the point.

What it costs

One or two files in a deploy. Pagination here is anchored — page 2 doesn't renumber itself because page 1 changed — so toggling a pin doesn't reshuffle the archive behind it.

Visually it costs even less: the pinned copy carries a small mark in the corner of its date badge, drawn in the neutral colour pair the badge already inverts to on hover. No new colour entered the palette. Seven keys are still seven keys.

Turning it on

Put pinned: true in the post's header, or press c in the properties dialog. Every list and picker marks it [PINNED] afterwards, so you can't forget which post is currently doing the talking.

The source of that exchange is exactly what you just read — speaker's name, a colon, the line:

Petr: I need a dialogue in a blog post.
./blog.sh: Write it in a chat fence. Name, colon, line.
Petr: That's it?

Wrap those lines in a code fence tagged chat and you're done.

You just read the feature. That's the whole documentation.

One take, fifty-seven seconds, no commentary and no cuts. A phone with a folding keyboard, and ./blog.sh running over SSH on the screen behind it.

What you're watching:

1. ./blog.sh with no arguments — a menu, arrow keys, one-key answers.
2. add opens the editor. The post is Markdown with a tiny frontmatter on top.
3. Saving builds the draft and deploys it to a hidden preview URL — which is where the video ends: the same draft open in a browser on the desktop, and then on a tablet.

That ending is the point. The draft is already a real page on the real site, behind an unguessable URL — reviewable from any device that can open a link, shareable with anyone you want feedback from. The one step the video doesn't show is a single menu choice — publish — after which the announcement toot goes out on its own.

No admin panel logged into, no step you couldn't do over SSH from a train.

Two footnotes for the sceptics. The real-time pace is the argument — that's why there are no cuts. And the whole wizard degrades gracefully: run it in a pipe and it falls back to plain line prompts with no escape sequences, so everything you just watched can also be scripted.