./blog.sh

Jak jsem si na sdíleném hostingu nastavil blog.sh

Sat, 19 Sep 2026 17:32:40 +0200

How did I set up blog.sh on my shared hosting
pavelchcepsat.cz

Pavel přestěhoval WordPressový blog ze sdíleného hostingu na blog.sh, a to přes obyčejné FTP. Postup popisuje krok za krokem: export WXR, import, rclone, zkušební běh, nasazení.

Stojí za přečtení, pokud tvůj web běží na hostingu, který nabízí FTP a nic víc.

#blogsh #wordpress #staticsite

Co se načte poslední, vyhrává

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

Dva skutečné weby nosí vzhled, který tento engine nikdy nedodával. sh.cynicky.blog je oblečený jako Ghost — úvodní karta přes celou šířku, tečkovaný rámeček, dlaždice místo prostého seznamu. arch-linux.cz je oblečený jako téma pro Hugo, konkrétně Blowfish — kompaktní lišta, blok s profilem, karty rozložené jako úplně jiná domovská stránka. Ani jeden nevytvořil fork enginu. Ani jeden neupravil šablonu. Oba dál přijímají obyčejný git pull.

Jeden stylesheet, načtený jako poslední

site.extra_css v config/site.yml udává cestu nebo seznam cest, které se načtou po vlastních colors.css a site.css enginu. To je celý mechanismus — skin je jeden tvůj soubor, který překresluje, co už na stránce je, a engine do něj nikdy nezapisuje, takže s ním aktualizace nikdy nemůže být v konfliktu.

Jen místní cesty: každá stránka nese style-src 'self' a stylesheet z jiného hostitele by prohlížeč prostě zahodil bez jediné chyby, kterou by kdokoli uviděl — sestavení proto vzdálenou cestu odmítne nahlas, dřív než to ticho nastane.

Jestli ten soubor patří do gitu, je samostatné rozhodnutí — commitni ho a druhý počítač už má tvůj vzhled, vynech ho a veřejný repozitář nikdy nebude nést design, který veřejný být neměl. Ani vlastní .gitignore enginu za tebe nerozhoduje ani jedním směrem.

Pravidlo, ze kterého plyne všechno ostatní

Načtení jako poslední znamená, že tvoje pravidla vyhrávají při stejné specifičnosti — včetně pravidel, která engine napsal pro úzké obrazovky, a to není ta část, u které by někdo čekal, že proti ní bude vyhrávat.

Skin sh.cynicky.blog nechává obsah plout vedle článku a dal mu šířku v procentech, aby odpovídala jeho vlastní šířce sazby. Na desktopu to vypadalo dobře. Pod 700 px má engine vlastní přeskládání: obsah se přesune nad text a pravidlo šířky se změní na auto, protože při takové velikosti už vedle není místo. Procenta ze skinu o tom nevěděla a platila dál — načtení jako poslední znamená vyhrát vždy, ne jen když se to hodí. Článek vyšel 155 pixelů široký na 390pixelové obrazovce telefonu.

Oprava obalí přepis do rozsahu, kde má skutečně platit:

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

Pod touto šířkou skin mlčí a přeskládání enginu může dělat tu jedinou práci, kterou už dělalo správně.

Na čem engine spoléhá, aniž to říká

Dvě menší pasti vzešly z druhého skinu, z arch-linux.cz, a obě mají stejný tvar: pravidlo, které vypadá čistě dekorativně, se ukáže být někde jinde nosné.

Zrušit navigační liště enginu přilepení je rozumné přání skinu. Na arch-linux.cz kvůli tomu ale přestalo reagovat na kliknutí i tlačítko pro přepínání motivu — ne proto, že by se tlačítko rozbilo, ale proto, že lišta seděla v CSS gridu, kde z-index funguje i bez position, a odlepená lišta si svou vyšší vrstvu ponechala a neviditelně ležela přes tlačítko. Přišel na to admin toho webu tím, že na přepínač skutečně klikl; na screenshotu by to nebylo vidět nikdy.

Druhá, menší: max-width na flex položce s flex-basis: 100% zmenší hypotetickou šířku položky, místo aby omezila její obsah — a tak jednou tělo článku skončilo vedle vlastního řádku s metadaty místo pod ním. Omezení patří na potomky, ne na box kolem nich.

Jedna stránka výpisu, ne celý feed

Stylesheet neumí číst adresu, takže úvodní stránka a /page/2/ byly pro CSS dřív k nerozeznání — což začalo vadit ve chvíli, kdy kterýkoli skin chtěl úvodní kartu jen na první stránce. Od 1.3.2 říká každého výpisu, o jaký druh jde:

.page-first .post-list-item:first-child { /* úvodní karta */ }
.page-cont  .archive-note { /* jen na pokračováních */ }

Dvě třídy místo jedné, záměrně — jediná značka na pokračováních by znamenala napsat vzhled první stránky bezpodmínečně a pak ho vlastnost po vlastnosti rušit, a pravidlo, které ruší jiné pravidlo, je přesně to, které pozdější úprava tiše přestane rušit.

Nahoře je sh.cynicky.blog — úvodní karta přes celou šířku, tečkovaný rámeček, dlaždice místo prostého seznamu a za tím ani jeden upravený soubor enginu. Vyhledávání zůstává polem v liště enginu, ne modálním oknem, které by mu dal sám Ghost, protože přestavět ho na modál by znamenalo vlastnit chování, které engine nikdy neslíbil. Žádný ze skinů, ani tenhle, ani ten z arch-linux.cz, se nikdy nesnažil o kopii k nerozeznání do posledního pixelu. Věrnost nebyla cílem. Cílem bylo patřit do rodiny.

Skin přestane být levným nástrojem ve chvíli, kdy potřebuje značky, které engine nestaví — v tu chvíli je poctivou volbou upravit šablonu, ne stylesheet, který se snaží něco předstírat. Než se k té hranici dojde, žádný systém témat není potřeba: žádné háčky, žádný registr, žádná hierarchie přepsání, kterou by bylo třeba držet v hlavě. Celou funkci nese jediný fakt. Tvůj soubor se načítá poslední.

—

P.S. — sh.cynicky.blog není tam, kde žije samotný cynicky.blog. Skutečný web stále běží na platformě Ghost a je aktualizován téměř každý den; sh.cynicky.blog má stejný vzhled a je udržován jako samostatná funkční instalace. Jeho autor se zabýval skutečnou migrací a rozhodl se zůstat tam, kde už byl – stojí za to to říci na rovinu, místo aby doménové jméno naznačovalo něco jiného.

./blog.sh 1.8

Mon, 14 Sep 2026 10:10:04 +0200

./blog.sh 1.8 je venku — vydání na GitHubu.

Vydání o tom, co se stane, když se něco pokazí. Každá stránka, feed a index se teď zapisuje do dočasného souboru a přejmenuje na místo, takže uložení přerušené plným diskem nebo sestavení zastavené uprostřed zápisu už nezanechá stránku v poloviční délce ani příspěvek o 0 bajtech, u kterého je starý text pryč. Studené sestavení tím zdraží zhruba o pětinu; sestavení z cache ne, takže běžný den publikování stojí přesně tolik co dřív.

Dvojí doručení už neznamená, že se něco stane dvakrát: příspěvek odeslaný z telefonu dvakrát nebo jedna potvrzenka doručená ve dvou kopiích najednou je teď jeden příspěvek a opětovný import exportu vlastního enginu už z 1200 příspěvků nedělá 2400. A adrese se už nevěří jen proto, že jako adresa vypadá — ../ ve slugu, v názvu mediálního souboru nebo v cíli přesměrování zůstane uvnitř webu, lokální nasazení zůstane uvnitř svého adresáře a přesměrování z feedu nemůže poslat stahování na localhost.

Před tagem prošlo pět úzce zaměřených revizí zápisové cesty, výstup sestavení, import a export, check a série; všechno, co našly, je opravené a přišpendlené testem, který na starém kódu padá. Většinu z toho nikdo nikdy nepotká. Co potkat můžeš: check se ptá na totéž co sestavení, takže stránka se slugem index.html už nezastaví každé sestavení, zatímco check prohlašuje archiv za v pořádku; export se už nezastaví na prvním rozbitém příspěvku a vrátí se domů i s prázdnými odstavci a vloženými prvky beze změny; série o dvaceti a více dílech se otevře od prvního dílu; a díl s číslem 08 už o své číslo nepřijde kvůli osmičkové soustavě.

Není co migrovat — git pull, sestavit, nasadit. První sestavení vykreslí každou stránku jednou; na mém vlastním archivu o 6 600 příspěvcích nahrálo následné nasazení jediný soubor, tahák k Markdownu. Celé poznámky →

Sestavení neví, kam míří

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

Někdo postaví celý web na notebooku, naimportuje do něj desetiletí starých příspěvků, prohlédne si každou stránku — a nic z toho ještě nikam nedorazilo. V env.sh není řečeno kam a nic dalšího na to nečeká: sestavení proběhne, archiv projde kontrolou, každá stránka se vykreslí na localhost. Sestavení neví, kde má web nakonec skončit, a vědět to nepotřebuje.

Totéž sestavení může začít na notebooku, o rok později se přestěhovat na pronajatý VPS a potom skončit na instanci Cloudronu. Mezi těmito přesuny se v obsahové pipeline nemění nic. Mění se odpověď na jedinou otázku — kam mají soubory jít — a odpovědět na ni může šest věcí.

Co o tom rozhoduje

DEPLOY_BACKEND v env.sh určuje cíl; hodnoty pod ním závisejí na tom, který to je. Všechno za tímto řádkem je u všech šesti stejné. Každý backend si vede vlastní manifest — SHA-256, velikost a čas změny každého souboru, který už nahrál — takže nasazení posílá vždy jen to, co se od minulého změnilo. deploy-web.sh --dry-run tento manifest přečte, aniž by se čehokoli dotkl.

Takhle vypadá výstup, spuštěný právě teď proti vlastnímu backendu tohoto webu:

$ ./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

Od posledního skutečného nasazení se nic nezměnilo, takže to manifest oznámí a tím to končí — stejnou větu by vypsal cíl git nebo rclone, jen s jiným řádkem nad ní, který říká, kdo odpověděl.

Manifest je ale pro každý backend zvlášť, takže když stejné sestavení poprvé namíříš na jiný cíl, první nasazení nahraje všechno — přesun je jedno úplné nahrání, ne opakování čehokoli, co sestavení udělalo.

Pravidlo určuje ten nejpřísnější

Jediný soubor nad 100 MB se odmítne při uložení i znovu při nasazení a limit je na všech šesti backendech stejné číslo — ne proto, že by všechny cíle sdílely tentýž strop, ale proto, že engine vybere ten nejpřísnější a všechny se ho drží. Web určený pro rsync tak zůstane nasaditelný i přes sftp a nikdo nemusí zjišťovat na vlastní kůži, který backend byl shovívavý.

To prozrazuje, že tohle není šest nahrávacích nástrojů vedle sebe: je to jeden model nasazení — jeden tvar manifestu, jedna bezpečnostní pojistka, jeden limit velikosti souboru — se šesti způsoby, jak se dostat na druhý konec. Backendy se liší tím, jak bajty putují; co smí putovat, není jejich věc.

Těch šest

surfer je výchozí — nastav SURFER_URL a SURFER_TOKEN a nic dalšího říkat nemusíš. Je to Cloudron Surfer, hosting, na kterém běží i tento projekt.

local zapisuje přímo do adresáře, a to pro kořenový adresář dokumentů za vaším vlastním serverem nginx nebo Caddy. O HTTPS se v každém případě stará webový server; CSP tohoto modulu je dodáván jako meta tag, takže v tomto ohledu není třeba nic konfigurovat, ani kdyby tento tag chyběl.

rsync míří na libovolný server dostupný přes SSH, na kterém je nainstalovaný rsync — nejuniverzálnější z šesti, protože to popisuje většinu VPS i dobrou část sdíleného hostingu.

git pushuje na GitHub, GitLab nebo Codeberg Pages, při každém nasazení force-pushem celé sestavení jako jediný commit. Vlastní doména vyžaduje nastavené GIT_PAGES_CNAME, protože hostitel drží tu adresu v souboru, který leží přímo ve větvi, již snapshot přepisuje.

rclone dosáhne na S3, R2, B2, WebDAV a cokoli dalšího, s čím umí rclone config komunikovat; přihlašovací údaje k bucketu zůstávají v konfiguraci rcloneu, ne v env.sh.

sftp je pro hostitele, kteří nemají rsync ani git: obyčejné SSH, dávkový sftp, jedno spojení na nasazení. Ověřování klíčem je potřeba nastavit předem — dávková úloha nemá terminál, ve kterém by odpověděla na dotaz na heslo, a spojení selže, místo aby čekalo na odpověď, která nepřijde.

Na kterém z těch šesti web běží, je jediný řádek v env.sh, zvolený jednou a jen zřídka přehodnocovaný — protože těžší polovina problému nikdy nebyl backend. Bylo to zajistit, aby nezáleželo na tom, který se vybere.

One line of colour

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

A reader changed one border colour in site.css, ran a rebuild, and waited while the build produced, byte for byte, every page that was already there. He asked why. The answer was one word in one list, and 1.7 takes it out.

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

The last thing a recorder writes

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

Someone opens a post with a video in it and presses play. The connection is fine. The video is not large. Nothing happens for a while, and then the video starts all at once, as if it had been waiting for permission.

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.

The same bytes, moved. Nothing is re-encoded.

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.

A bicycle nobody had to draw

Mon, 07 Sep 2026 16:12:00 +0200

The example configuration this engine ships carries a bicycle: a tag called kolo, and under it an written out by hand. It is there because there was nothing else to put there. tag_icons took the name of an icon the engine ships or a drawing of your own, and the ones it shipped were the eight content types — text, image, video, link, audio, quote, document, chat. A tag about cycling could wear the glyph for "audio", or somebody could spend an evening with a coordinate grid.

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.

The whole set, by name. Drawn on the same grid and stroke as the eight the engine has always shipped.

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

The address a post is about

Mon, 07 Sep 2026 10:11:00 +0200

Somebody sends you an article. You read it, and you have two hundred words to say about it -- not a review, the thing you noticed and one sentence about why. The post is mostly the other page, and the address it is about has to live somewhere.

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

A post that is about an address: the card sits above the text, and the post borrows its title.

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

What a post is, not what it says

Sun, 06 Sep 2026 17:17:00 +0200

Five parts of a series written over a spring, and the third went out without its series: line. The site did what it was told. Part three sat at its date and nowhere else: off the series listing, out of the links from one part to the next, and out of the count the other four wear: part four's page called itself part 3 of 4, standing in the slot the missing post should have had. The fix was one word.

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 gains [e] -- on a draft, on a scheduled post and on a published one alike.

The screen behind [e]. Two rows answer with the site's own default rather than yes or no -- that is the third state.

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.

The post that waited for a terminal

Sun, 06 Sep 2026 11:17:00 +0200

The post is written on the tram: a title, four paragraphs, two photographs with their descriptions. The switch above Send says Draft, which is what it says unless it is moved. Send, and the answer card comes back with the preview address. Then it sits. Putting a draft out was a command, and a command wants a terminal, and the tram has none.

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 page a post is written on: the same page on any phone, and the only one the engine publishes as a file.

The receiver knows that shape: one file in the delivery, called that. It stores nothing. It reads the slug and runs publish --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/.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.

./blog.sh 1.7

Sat, 05 Sep 2026 23:23:33 +0200

./blog.sh 1.7 is out. The page that writes a post on a phone now publishes it too, and it finds out what happened rather than being told: it mints a receipt before sending and asks the site for it every three seconds until the answer comes.

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

Everything else in 1.6

Sat, 05 Sep 2026 17:06:00 +0200

Five posts have covered the things 1.6 is about. This one is the rest, in the order an operator meets them.

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: , javascript: written as an entity, and an 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.

A badge that says what a post is about

Sat, 05 Sep 2026 11:06:00 +0200

Every post wears a date badge with an icon in it, and the icon says what kind of post it is: text, a picture, a video, a quote. On a blog where nearly everything is text, that icon is the same on nearly every card. Somebody running this engine put it plainly in issue #45: one sees the generic icon so often that it becomes invisible, or clutter.

1.6 lets a tag carry an icon instead.

tag_icons:
  - tag: "build"
    icon_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// 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 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.

Where a reader carries a post

Fri, 04 Sep 2026 16:52:00 +0200

A post gets read, and then it goes somewhere: into a toot, a message, an email to one person. Until now the reader did that by copying the address out of the bar. 1.6 puts a row of controls under the post for it — off unless share: names what you want, drawn in the order you name it.

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.

Written on a train

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

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

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

A page on the blog itself

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

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

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

A key, and nothing new on the network

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

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

What it refuses to do

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

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

What it costs

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

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

A post handed over as a file

Thu, 03 Sep 2026 16:42:00 +0200

Until 1.6 a post came from a person at a terminal. The wizard asked its questions, opened an editor, asked what to do at the end. Nothing else could write one: not a script, not a cron job, not a phone.

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

The time between deciding and the site saying so

Thu, 03 Sep 2026 10:41:00 +0200

Publishing a post used to cost the size of the archive, not the size of the change. A post dated today alters a dozen files. The build rendered every page in the archive and read every one back off disk to find that out.

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

What the build remembers now

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

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

What it still cannot skip

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

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

A note, not an authority

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

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

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

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

./blog.sh 1.6

Thu, 03 Sep 2026 08:25:43 +0200

./blog.sh 1.6 is out.

The build stopped rebuilding what nobody changed: a rebuild that changes nothing costs a seventh of what it did, an ordinary publish about two fifths. A post can be handed over as a file — by a script, a cron job, or the new page at /write/ on the blog itself, which sends from a phone over the SSH the server already has. Nothing new listens on the network.

Around those: a row of share controls under a post, an icon a tag can carry, a way out of the trash and the versions, and a photograph stored once instead of twice.

#blogsh #ruby #staticsite

Everything else in 1.5

Wed, 02 Sep 2026 10:31:00 +0200

Five posts covered the shape of this release. Here is the rest of it, a paragraph each.

A copy button on code blocks

Issue #44, from somebody running a blog full of terminal how-tos. It is always there rather than on hover: a phone has no hover, and a button only a mouse can find is one half the readers never get. Only on code blocks — a chat is a

, inline code is a bare

 — so it hangs on the block type, not on the tag. On an http:// install there is no button rather than a dead one, and it copies what the block stores, not what wrapped on screen.
Two things you will see
Every listing by content type has an icon now. The other four kinds of listing got theirs in earlier releases, which left these seven looking unfinished; the quotation mark is filled rather than stroked, because outlined at twenty pixels the pair closed up into something that read as the digits 99. And the page is framed on all four sides: a heavy rule has closed it off top and bottom since 1.3, but the sides stayed open, so on a wide screen the text had a beginning and an end and no shape. Off below 700 pixels, where the column already reaches both edges.
Where one paragraph ended and the next began
A search snippet is a post's text with the paragraphs taken out, so the last words of one and the first of the next meet as one broken sentence. A middle dot stands between them now — not an ellipsis, which already means "cut here" at the end of every snippet, and one mark with two meanings is how a reader learns to trust neither. On the reference archive, 593 of the 1,636 titled posts run past their first paragraph.
The appearance button, in a window that refuses to remember
Safari's private windows — and any profile with site data blocked — throw when localStorage is merely read, not only when written. That threw out of the last line of theme-toggle.js, so the code wiring the button up never ran: no cycling, no symbol, nothing. Both sides are guarded now, and the cycle asks the page which theme it is showing rather than the storage it may not have.
Thirty-four lines of your own configuration
Choosing a palette in ./style.sh deleted them. The last colour key is the last active key in its section, and the commented-out fonts: block underneath holds a line that uncomments to the same indentation as a colour — so the writer claimed it, and everything below it, as part of what it was rewriting. The file came back without its documented block, and the wizard reported success.
The other door to a photograph
./blog.sh add strips the coordinates out of a photograph, exactly as the documentation promises. ./blog.sh edit — the path people use far more — had grown a bare copy of the same work, and did not. Two implementations of one promise is one too many.
01.JPG and 01.jpg
An importer keeps the source URL's extension exactly as it was, case and all, and 01.JPG is an ordinary name in a real archive: Posterous served IMG_2669.JPG, and a decade of cameras wrote nothing else. The allocator compared bytes and handed a new picture 01.jpg believing it free; the copy asks the volume, and on macOS, or any Windows share, 01.JPG answers for 01.jpg. So the copy was skipped, the arrival's bytes were never written anywhere, the post showed the old photograph under both names — and check reported a reassuring "misnamed". Names are folded on every volume now: one that is free on Linux and taken on macOS is a picture that vanishes when somebody moves their site.
Somebody else's stylesheet, inside your post
An imported embed's HTML was rendered with its scripts, style blocks and stylesheet links intact. The site's policy already stopped the scripts — but the feed carries the same HTML and has no policy at all, and the style block was never inert anyway: style-src has to carry unsafe-inline for a post's own colour formatting. Both Instagram embeds in this house's archive carry body > iframe { min-width: auto !important }, reaching out of the embed to every iframe on the page. Nothing hostile; simply not this site's to decide.



An archive you cannot see is not empty
Tue, 01 Sep 2026 16:22:00 +0200
This site's approved comments and its post counters are two small JSON files, refreshed by a cron job every half hour and uploaded with the rest of the site.
Through 1.4, a tick that ran while the archive was not there would narrow both files to nothing and upload them. An absent or empty content directory answers with an empty list and no error, and an empty list reads exactly like "every announced post was deleted". The live site lost every approved comment and every counter at once. Exit 0, nothing said, nothing mailed.
The archive lives on a synced volume. A volume that has not mounted yet, or a working copy whose files are still arriving, is not an unusual Tuesday.
Not being able to tell is a reason to keep everything
That sentence is the fix, and it now runs in two tiers.
If the content directory is not there — or if the archive reads as empty while the previous files held anything at all — nothing is narrowed, and the run says why.
And if only part of the archive is unreadable, a post file that will not parse this minute, a half-written save, a cloud copy still arriving, nothing is narrowed either. Otherwise that gap would be read as a post that was deleted, and its approved discussion deleted along with it. Only a run that could read the whole archive is allowed to decide that something is gone.
The same mistake, one job over
The scheduled-publish cron had a sibling of this. It took a snapshot of the due posts when it started and wrote that snapshot back when it finished, so everything that happened in between was overwritten. An edit made while it worked was silently replaced with the older text. A post deleted in the meantime was recreated from the snapshot, published, and announced to a timeline that cannot be recalled.
Each post is re-read at the moment it is written now.
Why these two are worth a post
Neither of them is a crash. Both jobs ran, both exited 0, both reported success, and one of them was announcing things to the world while it did.
That is the failure worth being afraid of in a tool that runs unattended: not the job that stops, but the job that carries on confidently with a wrong idea of what your archive contains. A crash you find out about. This kind you find out about when somebody asks where their comment went.


Posts nobody meant to publish
Tue, 01 Sep 2026 10:21:00 +0200
An importer's worst failure is not losing a post. It is publishing one.
1.5 went through all eleven import adapters and the machinery underneath them looking for exactly that, and found it three times over, in three different files, made the same way each time.
An archive is the whole account
A Mastodon export is not your public timeline. The outbox holds your followers-only posts and your direct messages beside the public ones — and every standalone toot in it was being written as published. On the archive this was measured against that is 141 posts of 2,548, of which 132 are direct messages, each given its own page, its own sitemap entry and its own item in the feed. Nothing in the run's summary mentioned it.
The scope was in the export all along, exactly where ActivityPub puts it. Public in to is public. Public in cc is unlisted — a real address, out of the listings. Followers-only and direct become drafts: that keeps the author's words in the archive and off the site, which is the only reading of "not public" that cannot publish something by accident.
Gated at serve time is not gated
Ghost ships the full body of every members-only and paid post in its export, because a Ghost site decides who you are when it serves the page. Read by anything that does not make that check, every word anybody paid for is plain text sitting in a file.
They arrived published, untagged and uncounted. They now arrive as drafts, tagged, and counted in the summary — the reversible half of the decision, and a number the person running the import can act on.
A comment on the wrong line
Hugo's TOML front matter says draft = true. Written as draft = true # nekdy pozdeji — a note to yourself, on precisely the line where a person writes one — the value scanner took the comment as part of the value. That made the flag a truthy string rather than the boolean it looks like, and a truthy string is not true, so the post imported as published.
Somebody's unfinished writing went onto the open web because they annotated the flag that was supposed to hold it back.
The rule underneath
All three are one mistake wearing different clothes: the importer treated anything it could not classify as public. The rule runs the other way now. Not being able to tell whether something is publishable is a reason not to publish it — and to say so in the summary, with a count.
An import you have to audit afterwards is one you cannot trust. The point of a number in the summary is that you should not have to go looking.


Cut before it is written
Mon, 31 Aug 2026 16:12:00 +0200
A listing card used to be the whole post. The engine rendered every block of it into the page, and the stylesheet clipped the result at 500 pixels.
On the real front page that meant fourteen cards carrying between 794 and 2,616 pixels of content and showing 500. Of the page's 50,659 characters, 49,312 sat inside the clip. Thirty-three of its 154 focusable elements could be reached with the keyboard while being invisible on screen — links a sighted mouse user could not see and a keyboard user could not skip.
1.5 cuts the card before it is written. The stylesheet hides nothing.
That page went from 89,268 bytes of HTML to 41,155. Its largest card, 7,463 characters, is now 2,566. And "read more" appears exactly when something did not fit, rather than sitting under a card that was already showing everything it had.
The budget is in pixels, not characters
This is the part that had to be measured. A character budget is the obvious design and it is wrong, because characters do not measure height. A picture costs no characters and several hundred pixels. Written as a rule of "400 characters", the cut made 34 % of this archive's cards taller than the clip it was replacing — one of them 4,928 pixels tall.
So the budget is an estimated height, read off a real card: a 534-pixel content column, a 24-pixel line, about 78 characters to a full line, checked against twelve real paragraphs — eleven of which agreed. The estimate is approximate on purpose. The reader's column is narrower or wider than the nominal one, and so was the 500-pixel clip it replaces. What matters is that the cut lands between blocks rather than through one.
What is never cut
A picture. If the first block is a photograph it is kept whatever its height, because on a photo post the photograph is the post, and a card that opens with a cropped image is worse than a card that runs long.
A block made of rows — a hundred lines of shell, a long conversation, a list, a table — is cut to the rows that fit, at a row boundary. A paragraph that runs past the budget is cut on a word, with its formatting cut to match, so a link cannot end up pointing past the text it decorates.
And an author can overrule all of it
A line reading //--more--// splits a post into what it says about itself and what it actually says. The listing card, the link card and the announcement take the first half; the post's own page shows everything.
That one was asked for in issue #35 by somebody else running the engine, and their complaint was exact: a machine cut rarely lands on a good sentence, and the author knows where theirs is. A height budget is a decent guess about a card. It is not a claim to know where your post stops being an invitation.


Two pages the site built out of itself
Mon, 31 Aug 2026 10:11:00 +0200
Until now this engine could show you ten posts at a time and nothing else. /page/128/ is a real address on a large archive, and it tells you nothing about whether you have landed in 2009 or in 2014 — pagination is anchored from the oldest post, so the number moves under you every time something is published. The only complete list of anything lived in the terminal.
1.5 adds two pages that read the archive instead of walking it.
/archive/ — the shape of the whole thing
A row per year, with a strip of twelve months beside it. A month is shaded in one of four steps rather than simply lit or dark, because "has posts / has none" is not the question worth answering: on the reference archive a month holds anywhere from one post to eighty-seven, and drawing those the same would hide the one thing a map is for. /archive// is one line per post, by month.
Two levels and no more. A third would be some 280 pages of individual months — a great deal of building for a question nobody asked.
It is an index, not another listing: no excerpts, no pictures, no cards. And it is cheap by construction. Publishing a post rewrites the map and the current year; 2014 has not changed since new year's eve 2014 and never will, so a deploy that compares content has nothing to upload for it, ever again.
Twenty-four years on one page: 6,625 posts, from a year that holds 23 of them to a year that holds 641.
/tag/ — every subject the site has
The engine has always built a page per tag and never anything that showed them all. A site's own list of what it writes about lived in browse, or in the top eight of stats.
The list is sorted by the folded name, and that is not a detail. Ruby sorts strings by bytes, which puts every accented tag after z: on one real archive that is fifty-two of them, and the last six in byte order are školení, školitel, šumava, švihov, želnava, životvkorporátu. A reader looking for one of those between sirky and sport would not find it. stats folds now too — one question should not have two answers.
Each tag is a pill with its count riding inside it as a superscript, so a line that wraps cannot strand a number beside the wrong name. A reader can switch the order to by-count and the choice is remembered. But the page is built alphabetically and the switch is a script on top of it: a reader whose browser never runs that script gets the order the markup already holds, rather than a control that does nothing.
846 tags under 27 letters — and čarodějnice, česká televize and české dráhy under C rather than after z, which is what the folded sort buys.
Nothing to configure
Both pages are made out of the posts. There is no list to maintain, no front matter to add, and nothing that can drift out of step with what the site actually holds.
Every tag that has a page appears and no others. A tag carried only by a draft, a page or an unlisted post is drawn under its post as a flat pill with no link — listing it here would point a reader at a 404, and an index that lies about one address is an index you have to check.


A slug is an address, not a name
Sun, 30 Aug 2026 19:54:18 +0200
For most of this project's life, a post without a title had two names. Its own page called it by its date. Everything else — the browser tab, the link card somebody shares, every item in the feed — called it burtiky-opekame-hipstamatic-oggl-jane.
That is not a corner case. On the archive this engine is measured against, 2,754 posts of 4,418 carry no title. Sixty-two per cent of a site, going out into the world under an address.
A slug is made out of the words. It is not the words.
A slug is a machine's answer to "where does this live": lowercased, stripped of diacritics, joined with hyphens, cut to the first eight words. Every property that makes it a good address makes it a bad name. It has no capitals, no punctuation, and no idea where the sentence it was cut from was going.
1.5 takes the name from the same place the slug came from — the post's own opening — and stops in a better place.
Where it stops
A whole first sentence wins when one fits a window of four to twelve words, because a name that ends where the writer ended reads like a name. Failing that, the first eight words, which is exactly what slugs have always been cut to, so a post's name and its address stay recognisably the same post.
The sentence window is there for a reason a Czech archive teaches quickly. A Czech sentence puts its verb and its object at the end, so eight words usually stop just before the point. Where the sentence is short enough to take whole, taking it whole is the better cut.
One cut, not two. When the eighth word is a preposition or a conjunction it is dropped — "…vyplynulo, že" reads as a mistake where "…vyplynulo," reads as an interruption — and the dropped word then opens the rest of the text rather than disappearing between the halves. Whatever is on either side of a cut has to add back up to what was there.
What does not change
The heading on the post's own page is still the date it has been since 1.3. A post that never claimed a title is not handed one where its author would see it; it is handed one where a stranger has to recognise it — the tab, the card, the feed, the announcement.
And a post with a real title is untouched. This only ever fills a hole.


./blog.sh 1.5
Sun, 30 Aug 2026 08:58:55 +0200
1.5 is the release where the site learned to say what it holds. The release is on GitHub.
A post that never had a title used to be called by its address — on this project's own reference archive that was 62 % of it. Now it is called by its own opening words, everywhere except its heading, which stays the date it has been since 1.3.
Two new pages come with it: /archive/, a map of the whole site in two levels, and /tag/, every subject it has ever written about. Both are built from the posts themselves — nothing to configure and nothing to keep up to date.
Two things a post can now decide for itself: where its teaser stops (//--more--//, asked for in issue #35), and how much of it a listing card shows — cards are cut before they are written rather than drawn in full and hidden with CSS. And a code block carries a copy button, asked for by an operator running a blog of terminal how-tos.
Underneath, four days of adversarial review: two bug bounties, 237 confirmed findings, every one closed and pinned by a test that fails on the old code — or written down with the number of posts it actually affects, which for a third of them turned out to be zero.
Full notes → CHANGELOG.md


Tested like an enemy
Fri, 28 Aug 2026 16:52:00 +0200
1.4 went through four adversarial audit rounds before the tag: fleets of independent reviewers over real archives — real exports, a real 4400-post site, real deploy targets — each told to break the engine rather than confirm it. The findings numbered over a hundred. Every one was reproduced before it was fixed, and every fix is pinned by a test that demonstrably fails on the code it fixed.
The pattern that kept repeating
The uncomfortable lesson: each round's fixes were where the next round found its bugs. A fix for a comment-parsing rule deleted a hundred lines of somebody's config; a fix for that hid a widget's answers; the recovery advice written to save posts could destroy one. Four times in a row, the newest code was the most dangerous code in the tree — which is exactly why the last round audited nothing but the fixes themselves. It caught three regressions of mine before any user could.
Eighteen files
The proof I trust most is the quietest one. The whole release, rebuilt over a real 4400-post archive and compared byte for byte against 1.3.2, changes eighteen files: one stylesheet, two scripts, and one line in each draft preview. Published posts do not move by a byte. A release can rework the machinery this much and still owe its archive that kind of stillness — that is the contract, and now there is a diff that shows it being kept.
What you get out of it
Not a promise of zero bugs — nobody honest sells that. The promise is narrower and better: the failure modes that stay are the loud kind. check refuses what the build refuses. A crash cannot cost a post. A deploy pointed somewhere new uploads everything rather than trusting old records. When the next bug arrives, it should have to announce itself.


What a crash may cost
Fri, 28 Aug 2026 10:51:00 +0200
The queue can now swap two scheduled posts that share a slug across two years — with their media and their edit history riding along, because those are keyed by year and slug exactly like the post file. That sentence is short; making it true was most of a release cycle. The interesting part is not the swap. It is what happens when the power goes out in the middle of one.
The budget is zero
A move is several renames, and a crash can land between any two of them. The rule 1.4 holds to: whatever the moment, a crash may cost you the move — never a post. Files step aside under parking names before anything writes; a failed write puts everything back, byte for byte; a hard kill that strands a parked file leaves it where check finds it and says truthfully what it is.
The advice is part of the system
That last piece turned out to be the hardest. An early version of check's advice said "this is a stale copy — delete it", from nothing more than a file existing at the parked file's old name. But parking only happens when two posts share a slug, so the file standing there is by construction a different post — and after the right crash, the parked file is the only copy of yours there is. The advice now rests on the parked post's own identity: proven-stale names where the live copy sits; unproven says plainly that this may be the only copy, compare before you touch it, and never delete.
A recovery instruction that can destroy what it recovers is a bug like any other. It just took an audit aimed at our own fixes to see it.


The other half of check
Thu, 27 Aug 2026 16:42:00 +0200
./blog.sh check reads the whole archive and says what is wrong: media a post asks for and hasn't got, links to addresses nothing answers at, two posts that would be served at one address. Through 1.3 that was where it ended — a list of findings and an exit code, with the fixing left to you and a text editor.
--repair walks it with you
check --repair is the checker's other half: for each finding it offers the one repair that finding allows — an old address written into the target post's redirect_from, a relative link rewritten to the address it means, an orphaned file moved to the trash. Nothing is applied without a keypress, nothing is deleted outright, and a finding with no obvious answer — two posts colliding, an image only a human can judge — is shown and passed over rather than guessed at.
It proved itself before it shipped: on a real archive it took 238 findings down to 42, and the 21 repairs it proposed matched what a person had already decided by hand, one for one.
--json says everything
The screen shows twenty of a kind and totals the rest — right for reading, useless for a script. check --json prints every finding, uncapped, each with its kind and its data, so anything that wants to act — a migration script, a cron report — works from the same facts the screen summarizes.
And check itself got stricter
The rule behind the new findings is one sentence: an archive check calls sound must be one the build will run on. A file that will not parse, a date nothing can read, text that is not a list of blocks, a slug that is not one path segment — each is now a finding, because each is a build that stops. The one tool whose job is to say otherwise no longer says "sound" about any of them.


Deploy in your own language
Thu, 27 Aug 2026 10:41:00 +0200
The wizards were translated from the start; the narration around them was not. A Czech site watched its own deploy go by in English, one line above a Czech sentence — build warnings, announcement failures, import errors, the queue's repair instructions, all of it. Not broken, exactly. Just a house where half the rooms answer in a different language.
Sixty sentences moved home
1.4 finishes the job: the deploy's whole narration — header, progress, the closing tally, every degradation notice — plus all eleven build warnings, every Bluesky and Mastodon failure, and the sentences an import prints when a source dies. English, Czech and German carry the same set, and the suite enforces the parity, so a key cannot exist in one language and abort in another.
What stays as it arrived
The diagnostics inside the sentences do not get translated: an HTTP code, a server's raw answer, an exception's text. Those are evidence, and evidence is quoted, not paraphrased — the sentence around them is the site's, the thing inside it is the network's.
The plural trap
"Built 1 posts" is the kind of bug a translation multiplies — Czech declines counts three ways, German differently again. The counted lines are written label-then-number now (posts: 1), which no language has to decline. Boring is correct, and correct in all three at once.


The same language, spoken differently
Wed, 26 Aug 2026 16:32:00 +0200
Comments here are replies to a toot, and GoToSocial speaks Mastodon's API — so comments on a GTS instance should have simply worked. They did not, not once, and nobody saw it fail: arch-linux.cz, the first site to pair this engine with its own GTS instance, had never shown a single comment under any post. My own tests had Mastodon on both ends, so they could never have caught it.
Dialect is not language
Two accents were in the way. GoToSocial writes a status address in its own shape, and the engine's pattern insisted on Mastodon's — a numeric id where GTS answers with a 26-character ULID. And GTS requires a token even to read a public thread, where Mastodon hands it to anyone who asks. The first accent broke the address parsing; the second broke the entire idea of live comments, which is a visitor's browser fetching the thread — a browser you cannot give a token to.
Moderation is the door in
So on GoToSocial, comments are the moderated kind by construction: comments.approval: fav, and the cron reads the thread with the token, server-side, publishing the replies you star. The side effect is one Mastodon sites choose deliberately: visitors' browsers stop contacting your instance at all.
doctor --online now tests the capability, not the brand — can an anonymous request read the thread? — so a Mastodon instance in secure mode gets the same honest answer. And the fix was confirmed where the bug was found: the first starred reply on arch-linux.cz appeared under its post the same day 1.4 landed there.

./blog.sh

Jak jsem si na sdíleném hostingu nastavil blog.sh

Co se načte poslední, vyhrává

Jeden stylesheet, načtený jako poslední

Pravidlo, ze kterého plyne všechno ostatní

Na čem engine spoléhá, aniž to říká

Jedna stránka výpisu, ne celý feed

./blog.sh 1.8

Sestavení neví, kam míří

Co o tom rozhoduje

Pravidlo určuje ten nejpřísnější

Těch šest

One line of colour

What a build writes down

Why the colour cost the archive

What is still fingerprinted, and what that costs

When the record is not believed

What it costs

The last thing a recorder writes

Why it sits at the end

Reading where it sits

Moving it on the way in

The ones already in the archive

What it refuses to do

What it costs

A bicycle nobody had to draw

Fifty-five nouns

Why they sit beside the eight

Where it turns up

The order in the list is the priority

What it refuses to do

What it costs

The address a post is about

Three lines in the header

What the post is then called

A paragraph that is only a link

What a card's address may be

What it costs

What a post is, not what it says

Seven rows

What the screen is for

Three states, not two

What it refuses

What it costs

The post that waited for a terminal

One file, down the same connection

An answer the page goes and gets

What is in it, and what is not

What it still refuses to do

What it costs

Where the page is

./blog.sh 1.7

Everything else in 1.6

A way out of the trash and the versions

A photograph stored once

check knows a type it does not know

What three reviews found

Eleven places where a terminal was watching

A badge that says what a post is about

It replaces rather than adds

The order is the priority

Eight by name, or your own

On this site, since today

Where a reader carries a post

What is prefilled, and what is not

Three that are not links

Why there is no Pixelfed

One new file

Written on a train

A page on the blog itself

A key, and nothing new on the network

What it refuses to do

What it costs

A post handed over as a file

Where the wizard would ask, this refuses

--json: one object, nothing else

Draft, unless the file says otherwise

--untrusted

The time between deciding and the site saying so

What the build remembers now

`check` knows a type it does not know

`--json`: one object, nothing else

`--untrusted`