Where to start, by situation

The screenshot-*.png files here are the images embedded in the main README.

In a hurry? The Quick start below is a complete copy-paste path to a site running locally on your machine -- one block per platform. The numbered sections after it are the full reference, including picking a deploy target to put the site on the internet.

• Ruby 2.7+ (3.x is what the real deployments run) -- standard library only, no gems, no Bundler. Check with ruby -v; blog.sh checks too and says exactly this if the interpreter is too old.
• bash -- for the thin blog.sh / deploy-web.sh / refresh-sidebar.sh wrappers. (On Windows that means WSL2 -- see the quick start; there is no native cmd/PowerShell path.)
• A place to serve static files -- any of the six deploy targets below, from a Cloudron Surfer app to a plain directory behind your own nginx/Caddy.
• Optional: a Mastodon or Bluesky account (comments, auto-announce, sidebar widgets) and cron (widget refresh, scheduled publishing).
• Optional, only with media.convert_heic: true (converting iPhone HEIC photos to JPEG on save): an image tool the machine typically already has -- sips is part of macOS; on Linux any of heif-convert (libheif-examples), ImageMagick with the HEIF delegate, or vips. Without one, the engine refuses the file with instructions instead of breaking; off by default.
• Optional, only with media.remux_video: true (moving a video's index to the front of the file, and out of the QuickTime container, on save): ffmpeg. Without it the post is still saved and the engine names the command instead; off by default.

All of that as one table

The same thing in a form you can scan before installing anything. The right-hand column is what happens if it is missing, because that is the question worth answering: almost nothing here stops the engine, it just switches something off and says so.

No gems, no Bundler, no lockfile: the engine is the standard library and these binaries, which is why an upgrade is a git pull and nothing else.

./setup.sh is the config step: it asks for the settings a site needs, checks the answers as it goes, and writes config/site.yml and env.sh for you. Most questions can be skipped with Enter, which keeps what is there -- the ones that cannot are the site's title, short name, description, author and address for as long as they still hold the template's examples -- and nothing is written until you have seen the diff and confirmed it -- so it is also the way to change any of this later. If you would rather edit the files yourself, the numbered sections below are the full reference and section 2 still starts with the two cp commands; the wizard leaves both files commented and hand-editable either way.

macOS

The system Ruby is 2.6 from 2019 and Apple treats it as frozen, so the one real step is a current Ruby via Homebrew:

brew install ruby
echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
exec zsh
ruby -v    # 3.x now, not 2.6.10

(That PATH line is for Apple Silicon; on an Intel Mac it's /usr/local/opt/ruby/bin. brew install ruby prints the exact line for your machine at the end of its output -- trust that one.)

(No Homebrew yet? Install it first with the one command on brew.sh. git is already there on any Mac with the Xcode Command Line Tools -- macOS offers to install them the first time you type git.)

Then:

git clone https://github.com/DanielSnor/blog.sh.git myblog
cd myblog
./setup.sh           # a few questions -> config/site.yml and env.sh
./blog.sh add        # write the first post; publish or keep as draft
./blog.sh preview    # -> http://localhost:8000/  (Ctrl-C stops it)

The system nano is as old as the system Ruby -- if the editor step complains about options, set your own: export EDITOR=vim (or code -w, or plain nano).

An icon instead of cd myblog && ./blog.sh. On a Mac ./setup.sh ends by offering to put a launcher in Applications: an icon, named after the site and wearing its favicon, that opens Terminal in the site's folder and runs ./blog.sh. It is nothing more than that -- no window of its own, nothing blog.sh does not do -- and the answer to Enter is no, since a yes puts something outside this folder. ./setup.sh --launcher makes it at any later time, and makes it again for a site whose folder moved: the folder is written into the launcher, so one site has one launcher -- under one name. The launcher is called what the site is called: after a change of site.short_name the next --launcher makes one under the new name, and the old one stays where it was until it is dragged to the Trash.

Three things to know about it, all of them macOS's:

• The first double-click asks whether the launcher may control Terminal, and under the question stands one sentence, in the site's language, saying what the launcher does. Allow it. Refused, the icon does nothing, and the question is not asked again -- the switch is then in System Settings → Privacy & Security → Automation.
• blog.sh runs in the window Terminal opens as it starts, or in a new one when Terminal was already running. Either way Terminal keeps the window open after blog.sh ends, saying the process completed. Whether it closes instead is Terminal's own setting: Settings → Profiles → Shell → "When the shell exits".
• It lands in /Applications, or in ~/Applications for an account that may not write there. An application of the same name that blog.sh did not make is never replaced, and neither is the launcher of ANOTHER site called the same -- two sites nobody has named yet are both "blog.sh"; give one a site.short_name of its own. BLOG_SH_LAUNCHER_DIR=<folder> puts the launcher somewhere else.

Linux (Debian/Ubuntu shown; any distro works)

sudo apt update && sudo apt install -y ruby-full git

(ruby-full rather than the bare ruby -- see the default-gems note below. On Fedora: sudo dnf install ruby; on Arch: sudo pacman -S ruby -- both already complete.)

git clone https://github.com/DanielSnor/blog.sh.git myblog
cd myblog
./setup.sh           # a few questions -> config/site.yml and env.sh
./blog.sh add        # write the first post; publish or keep as draft
./blog.sh preview    # -> http://localhost:8000/  (Ctrl-C stops it)

Windows

blog.sh's wrappers are bash, so on Windows it runs inside WSL2 -- Microsoft's Linux environment, one command to set up. In PowerShell as Administrator:

wsl --install

Reboot when asked; Ubuntu opens and asks you to pick a username. From that Ubuntu terminal, it's the Linux path verbatim:

sudo apt update && sudo apt install -y ruby-full git
git clone https://github.com/DanielSnor/blog.sh.git myblog
cd myblog
./setup.sh           # a few questions -> config/site.yml and env.sh
./blog.sh add        # write the first post; publish or keep as draft
./blog.sh preview    # -> http://localhost:8000/  (Ctrl-C stops it)

Two Windows-specific notes: clone into the Linux home (~/myblog, as above), not /mnt/c/... -- file permissions (chmod 600 on your tokens) and speed only work properly on the Linux side; and http://localhost:8000/ works straight from your Windows browser, WSL2 forwards it. Git Bash instead of WSL2 mostly runs too, but the interactive menus degrade (mintty isn't a TTY to a native Ruby), non-ASCII output is garbled until the console is switched to UTF-8 (chcp 65001), and chmod protects nothing on NTFS -- with real tokens in env.sh, WSL2 is the supported route.

The engine has no build-time network dependencies: a machine with Ruby and bash can build the whole site offline.

On "no gems" and default gems. Everything in blog.sh is written against Ruby's core standard library -- nothing to gem install, ever, for the engine itself to run. The one nuance: the optional Pixelfed/RSS sidebar widgets parse XML with rexml, which Ruby ships as a default gem -- bundled with a normal ruby install, but some Linux distributions split their Ruby package and leave default gems out of the minimal one. Importing is not optional about it: every XML source reads through rexml, which is WordPress, Blogger, Squarespace, podcasts, any RSS or Atom feed, the Wayback rescue and LiveJournal. If none of that is in your way -- no XML import, no widgets.pixelfed/widgets.rss -- it never comes up; if it is, and you see a LoadError about rexml, either gem install rexml or install your distro's fuller Ruby package -- e.g. ruby-full instead of the bare ruby on Debian/Ubuntu (Arch's own ruby package already includes the full standard library, no separate install needed there). ./blog.sh preview, by contrast, needed no such caveat to begin with: it's a small built-in static server (lib/preview_server.rb), not the webrick-dependent ruby -run -e httpd one-liner some other guides suggest.

One clone = one site. Everything personal (posts, media, config, secrets) is gitignored, so pulling engine updates later never touches your content -- see Updating the engine.

cp config/site.yml.example config/site.yml

Or let ./setup.sh do it: it seeds the file from this same example -- comments and all -- and fills in the answers you give it, which is the same file you would have written by hand, minus the chance of a tab where a space belongs. It covers the site block, the comments network and the deploy target; ./style.sh covers banner, about, footer, social, colors, fonts, widgets and nav. Both are re-runnable and neither takes anything away from editing the file directly.

If you do edit it directly -- which is a first-class way to use this engine, not a fallback -- run ./blog.sh doctor when you are done. It reads the file you just wrote and reports every problem in it at once, which is the half a hand edit does not get for free: an unclosed quote, a tab, a value in the wrong section, a token in env.sh with no section to use it. It is also the answer when a YAML error names a line that looks perfectly fine -- the parser stops where things stop fitting, which can be a long way from the mistake.

The example is fully commented. The short version:

• Required: site (title, short_name, description, author, lang, locale, base_url) and banner. That alone is a complete, working site.
• about and footer introduce the site and close every page; the example ships both filled in. Neither is required: an emptied value takes its section with it -- heading and all -- rather than rendering empty, and a deleted block reads the same as an emptied one.
• Optional, each activates only when present: analytics, social, widgets (toots / pixelfed / commits / bluesky / rss, each independently), mastodon or bluesky (comments + auto-announce -- exactly one, see step 8), comments (which replies get published -- same step), colors (7 keys per light/dark mode -- omitted keys fall back to the built-in blue palette; whole palettes ship in config/palettes.yml, and ./style.sh shows you a preview -- light and dark side by side -- and writes the one you pick into this section, so you never have to choose fourteen hex values by hand or blind), fonts (the banner title's and claim's font stack and size, plus any .woff2 you put in assets/fonts/ -- omitted keys fall back to the built-in JetBrains Mono at 45px/20px), nav and layout (what the pages are made of -- below), publishing.slots (the times posts usually go out, so scheduling stops asking for a date -- Writing), publishing.allow_partial (on a site of several languages, lets a post out without the words of every one of them, unasked -- Localization), media (convert_heic, remux_video and strip_location, all discussed under Writing from a phone), tag_icons (an icon a tag carries, on its own listing and on the date badge of every post that has it -- The archive), share (the row of controls under a post, drawn in the order you name them -- The archive), write (write: true publishes a page at /write/ to write a post on from a phone -- Writing), and seo (block_ai_crawlers writes a maintained list of the crawlers that collect text to train on into robots.txt, robots_extra is appended verbatim -- off by default, because wanting to be findable in an answer somebody gets from a machine is a legitimate position and the engine does not take it on your behalf either way).

The commits widget reads GitHub unless you give it instance -- the address of a Gitea or Forgejo server (Codeberg, your own git). The address is the whole configuration: nothing else has to be said, because it already answers which kind of host this is. That path costs one request where GitHub costs one per commit, since a Gitea activity item carries the commits it is about.

social, footer.links and nav are lists, and a list key holds a list or nothing at all: emptiness is a legitimate answer everywhere. Anything else under one of them -- a single URL pasted where a list belongs -- is a mistake doctor names and the build reads as empty, rather than a traceback out of an engine file.

social is the row of icons in the footer. Each entry takes name, url and either icon (a name from the built-in set: the network marks mastodon, pixelfed, linkedin, github, gitea, forgejo, codeberg, gitlab, bluesky, instagram, threads, facebook, x, youtube, rss, email -- or any of the general drawings the engine ships for tag icons, globe for somebody's other site among them, listed in operations.md) or icon_svg (your own markup), plus an optional rel that is passed through to the rendered link. rel: "me" on the Mastodon entry is what gets your site verified -- the green check mark next to it on your profile: Mastodon fetches the address from your profile's metadata field and accepts it only if that page links back to the profile with rel="me". The footer is on every page, so pointing the profile field at your home page is enough; the entry's url has to be the profile as Mastodon shows it (https://instance/@handle). Several entries may carry it. Bluesky verifies domains a different way (DNS or /.well-known), so rel: "me" does nothing for a Bluesky entry.

site.lang selects locales/<lang>.yml for every generated string -- en, cs and de ship with the engine; a partial locale falls back to English per key. Adding another language is data, not code -- see Localization.

site.locales is the list of languages the site publishes, and it is only needed when that is more than one. The language in site.lang keeps the site root; every other one is built into a root of its own (/de/), with one copy of /assets/ and one writing app shared between them. The words of a post in another language are written with ./blog.sh translate (see Writing), and ./blog.sh rebuild produces every language in one go. Leave the key out and nothing about the site changes -- no switcher, no alternates, nothing in the markup.

site.timezone (an IANA name like Europe/Prague) is the zone every timestamp the engine writes is expressed in. Set it if you'll ever publish from a server, because a server's clock is usually UTC: without it, schedule reads "10:30" as 10:30 UTC, and a post written after midnight local time can be dated to the previous day. Omit it to use the machine's own zone. A name the system doesn't know is refused at startup rather than silently treated as UTC. It also governs the dates readers see, including the sidebar widgets, whose sources report UTC. Existing posts keep the stored offset -- setting this later rewrites no history, it only changes the day shown for posts whose local day genuinely differs (and never a post's URL).

The palette and the header's type

colors.light and colors.dark take the same seven keys -- bg, text, meta_text, accent, nav_bg, border, pill_bg -- and the build compiles them into assets/css/colors.css. Everything else the stylesheet needs is derived from those seven rather than configured separately: the card background, the nav's text and border, the hover states of links and badges, the search field's background. That is why there are seven keys and not twenty, and why a palette cannot end up internally inconsistent. Omit the section entirely and the site uses blog.sh's own blue (DEFAULT_COLORS).

assets/css/site.css is the other half, and it is not generated: layout and structure, plus the few colors that are fixed because they work against any palette -- white on accent surfaces, the dark scrims behind the banner overlays and the lightbox, the search field's grey placeholder. Changing colors: is configuration; editing that file is editing an engine file, with the pull conflicts that implies (see step 9).

fonts.banner_title and fonts.banner_claim take a CSS font stack each, fonts.banner_title_size and fonts.banner_claim_size any CSS length, and they compile into that same generated stylesheet. Drop a .woff2 into assets/fonts/, declare it under fonts.faces, and the header is in your own type; say nothing and it stays self-hosted JetBrains Mono at 45px/20px. Narrow screens scale from whatever size is configured, so there is no second pair of keys to keep in sync.

The menu, the regions and a stylesheet of your own

Four more settings decide what the pages are made of rather than what they look like. Each has a default that leaves a site saying nothing exactly as it was, so none of them has to be touched.

nav: replaces the menu bar the build otherwise derives from the content types that actually have posts. An entry takes a label plus either a tag (a tag's slug, which becomes /tag/<slug>/) or a url taken as written -- so an item can point at a post, at a generated page, or off the site entirely:

nav:
  - { label: "Home", url: "/" }
  - { label: "Photographs", tag: "photo" }

An entry missing either half is skipped rather than rendered as an empty link. An empty list is a decision rather than a mistake: the entries and the button that opens them are gone, which is also how a site turns the menu off, so there is no second key for that. The bar itself stays, since the search field is rendered inside it. nav: with nothing under it at all -- the key left standing after its entries were deleted -- reads the same way, because a key that is written down is an answer; leave the key out entirely to ask the engine for its own menu again.

layout.sidebar and layout.hero switch whole regions on and off. The sidebar is on unless you say otherwise -- though it is only drawn when something would stand in it, so a site with no about text and no widgets gets its full width back without having to say so; the hero -- the post's first usable image lifted out of the text and run full width above the title -- is off unless you ask, because it reshapes every post page it touches and a site is entitled to keep the shape it has. A single post can still ask for one either way with hero: in its own header (see Writing). They are switches for regions, not for how a region looks: what things look like belongs in a stylesheet, and a key per visual property would turn this file into a stylesheet written in YAML.

site.extra_css is that stylesheet -- one path, or a list of them, loaded after the site's own, so a skin can live in a file of yours instead of in an edited engine file with the pull conflicts that implies (step 9). Local paths only (/assets/css/mine.css): every page carries style-src 'self', so a stylesheet on another host would be discarded by the browser without an error you would ever see -- the page would simply render undressed -- and the build refuses it out loud instead.

site.page_size is how many posts a listing page holds; 10 without it. Worth setting once, before the first deploy: pagination is anchored to the oldest post precisely so page contents never change as new posts arrive, and changing the size later renumbers every page in the archive.

Four starting points

Every key above is optional except the handful in site: and banner:, which is easy to say and hard to act on when you are looking at six hundred commented lines for the first time. So: four kinds of site, and the keys each one actually turns on. Everything not named stays at its default, and a default is a working site.

Written here rather than shipped as four site.yml variants on purpose. A copy of the config is a copy that goes stale the first time a key is added, and then somebody starts from a file that quietly disagrees with the engine. The reference is config/site.yml.example; this is a reading order through it.

A plain blog. site: (title, author, base_url, lang, timezone) and banner:. That is the whole minimum, and the file says so at the top. Add about:, footer: and social: when you want the chrome filled in.

A photo blog. As above, plus media.convert_heic: true if the pictures come off an iPhone, and media.remux_video: true if there are videos and ffmpeg is on the machine. Leave media.strip_location alone: it is on by default and that is the setting that keeps your address out of the pictures. Consider a smaller site.page_size -- a listing card is measured in height, not characters, so a page of photo posts is several times taller than a page of text ones.

A newsletter. publishing.slots: so posts go out on a schedule rather than when you happen to be at the keyboard, and cron to run it (see operations). The announce settings live in env.sh, not here. comments.approval: fav if replies should appear only once you have favourited them.

A Fediverse-facing site. comments: pointed at your instance, widgets: for the sidebar, and the Mastodon or Bluesky credentials in env.sh. seo.block_ai_crawlers: true if you would rather the text was not scraped for training; it writes the robots rules and nothing else.

env.sh holds secrets and per-environment values; it is gitignored and mode 600 because live credentials go in it. An unedited copy is enough to try everything locally -- with no deploy target configured, uploads are skipped (logged, not an error).

The one value worth knowing about right away is SITE_BASE_URL: the canonical URL normally comes from site.base_url in config/site.yml (step 2), and this env.sh value overrides it when set -- it exists so a staging or local environment can point somewhere other than production while building from the same config. One site, one URL? Set site.base_url and leave this out.

Watch the order they start in: the example above ships SITE_BASE_URL active and pointing at https://example.com, so filling in site.base_url carefully and leaving this file alone gives a site that still calls itself example.com in its feed, its sitemap and every share preview. Either comment this line out or give it the same address. ./setup.sh writes both to the same value for exactly this reason, and ./blog.sh doctor reports the address that would actually be used rather than the one in the config.

./style.sh does that part for you -- give it the path to an image and it copies the file into place, reads its real dimensions and writes them, so the pair can never drift from the file. ./blog.sh doctor reports it if they ever do.

The favicon is used three ways from that one file: the <link rel="icon">, an apple-touch-icon (iOS scales it down for a home-screen bookmark), and a generated /favicon.ico for clients that request the root path without reading the link. A square PNG of 180 px or more covers all three.

The banner gets site.short_name rendered top-left and site.description bottom-right (wrapping to several lines if it is long), each darkening the corner it sits in so it stays readable against any image -- and only that corner, so a banner with both overlays off is shown exactly as authored. A calm image still works best. Each is independently optional: banner.show_title and banner.show_claim (both default true) decide whether they render at all, and colors.<mode>.banner_title / colors.<mode>.banner_claim override their color per light and dark mode -- by default nav_bg in light, white in dark. banner.claim overrides only the overlay's text, in Markdown or raw HTML (a manual <br>, say); site.description itself stays plain text everywhere else it is used, in the meta description and the feed. Their typeface and size are fonts.

banner.show_image: false leaves the picture out of the header. The short name and the description then stand on the page itself, one under the other at the left edge, and the whole header is still the link home. Their colours default to the page's own text and meta_text instead of the pair chosen for reading over a picture -- banner_title / banner_claim still override them -- and their sizes are scaled down from the configured ones (32px and 16px with the defaults), since 45px is a size for a line laid across a picture. Leave src, alt, width and height as they are: src is also the picture a page with none of its own is shared with, and alt becomes the name of the link. It is a key to set by hand; ./style.sh does not ask about it.

add always creates a draft and offers publishing interactively -- see Writing for the full authoring flow.

Replacing an existing blog? Bring the old content in before you deploy, so the first published version of the site is already complete. ./import.sh walks you through it -- Bluesky, Mastodon, Pixelfed, Tumblr, a Twitter/X archive export, or WordPress and any RSS/Atom feed -- and always previews what it would write before writing anything. See The archive → Importing, and ./import.sh --help for the scriptable equivalents.

./scripts/deploy-web.sh --dry-run   # shows what would upload, touches nothing
./scripts/deploy-web.sh             # first real deploy (uploads everything once)

Every later deploy uploads only new/changed files -- a SHA-256 manifest (.deploy_manifest*.json, one per backend) tracks what the target already has, while .deploy_baseline.json records the shape of the last build the safety guards accepted. Both are gitignored and both are disposable.

The first deploy is rarely the one you run by hand. From here on the engine deploys as part of writing: saving a draft builds the site and deploys it, because a draft's preview is a real address on the real site (see Writing → Writing and publishing). So the target is written to the first time you save anything -- not the first time you type deploy-web.sh. Whatever is already at that address under a name the build also uses is replaced, and a placeholder page is exactly such a name.

If the target still holds something you want to keep -- a "coming soon" page, an old site you have not moved yet -- do not point env.sh at it until you are ready. An unedited env.sh deploys nowhere and everything else works, so a whole site can be written, previewed locally and imported into before any address of yours is touched; set the target when the site is ready to be seen. Reported from the outside, and it cost somebody their placeholder.

The other way round, nothing is removed. A deploy writes the site's files and deletes only files an earlier deploy of this site wrote; whatever else was in the target stays. After a previous site that matters: a host typically serves index.php before index.html, so an old WordPress front page goes on answering over the new one, and an old .htaccess can go on rewriting addresses the new site depends on. Clear the old site out of the target before the first deploy -- over FTP, with the client or file manager you used for it -- and keep only what the host itself put there. (The git backend is the exception: every push replaces the whole branch.) ./blog.sh doctor --online lists what stands in the target's root that the site does not put there -- run it once the target is set, before the first deploy. What stands there on purpose (screenshots an issue links to, a file a search console asked for) goes under deploy.keep in config/site.yml, and doctor stops naming it; .well-known/ it never names.

One thing to know before you write your first post with a big attachment: a single file over 100 MB is refused, at save time and again at deploy time. The limit is the same for every backend so the site stays portable between them -- the strictest supported target refuses anything larger. See Deploying for the rest of the guards.

surfer (Cloudron Surfer -- the default)

export SURFER_URL=https://surfer.example.com
export SURFER_USERNAME=...     # your Cloudron username, not the e-mail
export SURFER_PASSWORD=...     # an app password: Cloudron profile -> App Passwords
export SURFER_REMOTE_DIR=      # optional subdirectory; empty = app root

No DEPLOY_BACKEND needed -- surfer is the default whenever SURFER_URL is set.

Surfer 7 (September 2026) signs in with the Cloudron user and an app password -- one you create for the Surfer app in your Cloudron profile, not the password you sign in to Cloudron with. The access token of Surfer 6 and earlier (SURFER_TOKEN) is still read, but Surfer 7 answers it with HTTP 401, and the deploy then stops at the first file and says so. Moving over is two lines in env.sh: add SURFER_USERNAME and SURFER_PASSWORD and leave SURFER_TOKEN where it is. They can go in before the app has updated: a Surfer older than 7 answers the password with an error (HTTP 500), and the run then goes on with the token -- every run tries the password first, so the day Surfer 7 arrives it takes over by itself. ./blog.sh doctor --online says which of the two Surfer took.

local (a directory on the same machine)

export DEPLOY_BACKEND=local
export DEPLOY_TARGET_DIR=/var/www/mysite

For a docroot served by your own nginx/Caddy, or a mounted volume. Your web server handles HTTPS (Caddy does it automatically; certbot for nginx). The engine's CSP arrives via a meta tag so no header configuration is required -- but if you can set real HTTP headers, nothing stops you from adding more.

rsync (any SSH host)

export DEPLOY_BACKEND=rsync
export RSYNC_TARGET=user@server:/var/www/mysite
export RSYNC_SSH="ssh -p 2022"   # optional, only for a non-default ssh

The most universal remote option -- works against any VPS or shared host with SSH and rsync installed.

git (GitHub / GitLab / Codeberg Pages)

export DEPLOY_BACKEND=git
export GIT_PAGES_REMOTE=git@github.com:you/yoursite.git
export GIT_PAGES_BRANCH=gh-pages       # optional, this is the default
export GIT_PAGES_CNAME=www.example.com # optional custom domain

Free hosting with HTTPS. Setup on the host's side (GitHub shown, GitLab/Codeberg analogous): create a repository, then Settings → Pages → Build and deployment → Source → "Deploy from a branch" → gh-pages. Every deploy force-pushes the build as a single-commit snapshot; a custom domain must be set via GIT_PAGES_CNAME (the host stores it as a CNAME file in the branch, which a snapshot push would otherwise wipe).

rclone (S3, R2, B2, WebDAV, FTP, ...)

export DEPLOY_BACKEND=rclone
export RCLONE_TARGET=r2:my-bucket/site
export RCLONE_ARGS="--s3-acl public-read"   # optional provider flags

Run rclone config once to set up the remote -- credentials live in rclone's own config, never in env.sh. Needs the rclone binary installed -- from your distribution's packages or from rclone.org, not as a snap. The snap is not published by the rclone project, and it is confined to your home directory: with the site anywhere else (/srv, /var/www, /opt) it cannot read a single file of it, and says so as "no such file or directory" about a file that is plainly there. ./blog.sh doctor notices the snap and says when the site is out of its reach.

A plain FTP host -- the kind a shared hosting plan gives you, with no SSH to it at all -- goes through rclone as well. In rclone config pick the type ftp and give it the host, the user and the password; then

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

Nothing else is needed: the engine tells rclone exactly which files to send and which to delete, so it never asks the server for checksums, which FTP cannot give. If the host offers FTPS, turn it on in rclone config (explicit_tls) -- plain FTP sends the password in the clear.

If the deploy fails with the server complaining about too many connections -- shared hosting often allows only a few per account -- make rclone open one at a time:

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

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

sftp (hosts with neither rsync nor git)

export DEPLOY_BACKEND=sftp
export SFTP_TARGET=user@server
export SFTP_REMOTE_DIR=/var/www/mysite   # optional; nested paths must exist
export SFTP_ARGS="-P 2022"               # optional

Uses openssh's sftp in batch mode -- one connection uploads exactly what the manifest says changed. Set up SSH key auth first; a password prompt would block the batch.

1. Clone the repo on the server, repeat steps 2-6 there. env.sh stays on the server only -- it never syncs anywhere.
2. Install the widget cron (see Running it).
3. For writing from a phone, prepare the incoming/ staging directory: any SSH/SFTP account that can write into <repo>/incoming/ works. A dedicated user without sudo, limited to SFTP, is the safe shape -- photos are uploaded there by name and referenced as bare filenames in posts (see Writing).
4. For a post sent whole from a phone, add the key the shortcut uses to authorized_keys with a forced command pointing at scripts/receive.sh -- the line, the RSA requirement and the size ceiling are in Writing. Nothing new listens on the network; it travels over the SSH the server already has.
5. In a container setup (Cloudron and similar), the engine lives inside the container's persistent data directory and commands run via docker exec / the platform's terminal -- the engine itself doesn't care, it's just Ruby + bash in a directory.

Mastodon:

1. In config/site.yml, uncomment the mastodon: block -- the header line included, which is the half that is easy to miss -- and set mastodon.instance. This switches on comments, per-post stats and the auto-toot on publish.
2. On that instance: Preferences → Development → New application, scope write:statuses. Put the token into env.sh as MASTODON_ACCESS_TOKEN.
3. For the "recent toots" sidebar widget, widgets.toots.account_id wants the numeric account id, not the @handle -- find it at https://<instance>/api/v1/accounts/lookup?acct=<username>. (The widget's instance falls back to mastodon.instance.)
4. mastodon.toot_length is your instance's character limit, 500 by default. Set it if yours differs -- the announcement's perex is budgeted against this number, so a limit set too high gets the post rejected at publish time and one set too low just wastes room. mastodon.link_length is the other half of that arithmetic: Mastodon charges every link a flat 23 characters whatever it measures, and says so in its own API (characters_reserved_per_url). Leave it alone unless your server answers with a different number.

Bluesky:

1. In config/site.yml, set bluesky.handle (e.g. you.bsky.social); bluesky.pds only if you self-host a PDS.
2. On Bluesky: Settings → Privacy and security → App Passwords (bsky.app/settings/app-passwords) → create one, and put it into env.sh as BLUESKY_APP_PASSWORD -- never the account password.
3. Announcements fit Bluesky's 300-grapheme limit automatically (the excerpt shrinks; title, link and hashtags never do), with the link and hashtags clickable. Comments are read from Bluesky's public AppView by the visitor's browser -- no token involved on the page.

Optional: publish only the replies you star.

By default every reply to the announcement appears under the article. comments.approval: fav in config/site.yml changes that to: a reply appears once you favourite it, from whatever Mastodon or Bluesky client you already use. Your own replies need no star. Everything else stays on the network and off the blog.

comments:
  approval: fav      # or "off" (the default)

The moment you switch this on, every comment already on the site disappears. Moderation publishes only what you have starred, and at that moment that is nothing -- a site with years of replies goes quiet in one rebuild. They come back one star at a time, so plan the switch for a moment when you can go and star the keepers right away, and run ./scripts/refresh-sidebar.sh --full once afterwards to settle old posts on the spot instead of within the week.

Three things have to be true for it to work, and ./blog.sh doctor (add --online for the token check) says so when they aren't:

1. scripts/refresh-sidebar.sh has to be in cron (see Running it). "Did I favourite this?" is a question only an authenticated request can ask, and the token can't be shipped to a browser -- so cron reads the thread and writes public/comments.json, and the page renders from that. Without that cron job nothing new ever appears.
2. The token needs read:statuses alongside write:statuses. On Mastodon that is a choice; on GoToSocial it is the only way comments work at all (see the note below). Reissue it under Preferences → Development if yours predates this: a token without it gets a perfectly good answer with the favourited field left out of it, which reads as "approved nothing". On Bluesky the existing app password is enough.
3. You have to go and star the comments worth keeping -- see the warning above the list.

GoToSocial. Live comments cannot work there, whatever you configure: every read of a thread needs a token, all four of its authentication requirements are on, and a token cannot be put in a visitor's browser. Turn on comments.approval: fav -- the cron reads the thread with the token and only the replies you star reach the page. Two more things worth knowing: the token is made under Settings → Applications → New Application (not Preferences → Development, which is Mastodon's path and does not exist here), with the scopes written space-separated -- it needs read:statuses as well as write:statuses, and both fit in one token because GoToSocial has granular scopes. And a GoToSocial instance usually allows 5000 characters rather than 500, so mastodon.toot_length is worth setting to whatever your server's statuses-max-chars says. doctor --online checks the first of these for you and says so in one sentence.

Worth knowing before switching it on:

• Approval is not instant -- up to one cron interval, and for a post older than ~90 days up to a week, since old posts are only refreshed occasionally. ./scripts/refresh-sidebar.sh --full does it now.
• A favourite is public on both networks. Anyone can see which replies you starred, and replies starred in the past count as approved.
• The side effect nobody asks for and everybody gets: with the thread already read server-side, the visitor's browser stops contacting the network at all, and the page's CSP drops its connect-src grant to it. Avatars are still loaded from the instance hosting them.
• It keeps replies off the blog. It cannot remove them from the network, where the thread stays public and this site still links to it. Block, mute and report remain the tools for that.

rebuild, not ruby build/build_blog.rb: the build script renders one language per run, and rebuild runs it for every language the site publishes and then deploys. On a site in two languages the bare script followed by a deploy leaves the second language's pages as the previous version built them -- and uploads them that way.

main is the release branch: a clone on it gets each release by git pull. A clone that was put on a release tag (git checkout v1.8) is on no branch, and git pull refuses with "You are not currently on a branch"; move it to the next release by name instead:

git fetch --tags && git checkout v1.9

The first build after an upgrade may be a full one -- the engine's own fingerprint changed, so the record of the last build is thrown away -- and it writes .build_cache.json in the installation directory, which is per-machine, gitignored and always safe to delete. Deploy the assets with it: a page that cannot fetch assets/js/share.js logs a 404 on every load.

Going back a version is git checkout <tag> and a rebuild, and what the newer version was given to work with is looked at first, because the older one does not treat all of it alike. From 1.10 back to 1.9: take series: and language_name: out of every config/site.<lang>.yml, or the build stops on them and nothing is deployed -- a language's file is where 1.9 refuses a key it does not know. on_this_day under widgets: it does not refuse: the build says one line about it, doctor marks it, and the card is simply not drawn. And site.author_name, banner.show_image, layout.lead_card and publishing.allow_partial it passes over without a word, so the pages go back to what 1.9 makes without them -- the banner's picture is shown again, for one, and a site of several languages is asked about every post again. Old addresses a translation was given (translations.<lang>.former_slugs) stop being answered -- 1.9 does not read them, and a translation saved there is written without the list, so those addresses are not in the post on the way forward again either. What 1.10 left in the installation folder for itself (.on-this-day.*.json, .search_index.json, .last-sidebar-run) is safe to delete. The posts, the media and the rest of the configuration are otherwise untouched in both directions.

Per-deployment files (content.nosync/, media.nosync/, config/site.yml, config/site.<lang>.yml, env.sh, incoming/, trash/, drafts/, manifests) are gitignored and survive any pull untouched. The one thing to watch: if you've edited engine files in place (templates, CSS), a pull can conflict -- keep such customizations as commits on your own branch so git merges them for you. config/palettes.yml is one of those: it ships with the engine, so a palette of your own added to it is an edit in place. The wizards also leave a .bak of whatever they rewrote -- config/site.yml.bak, env.sh.bak -- which is how you take a wizard run back by hand. Nothing deletes them, and the env.sh one holds your previous tokens at the same 0600, so remove it once you have rotated a token.

./blog.sh with no arguments opens a numbered menu; every command also works directly (./blog.sh add, edit, publish, ...). The flow is built around drafts:

1. add opens $EDITOR with a frontmatter template (title, tags, type) -- the in-editor hint links to the /markdown/ syntax reference on your own site. Saving always creates a draft, and the draft appears at a hidden /draft/<token>/<slug>/ address with noindex -- invisible in every listing, shareable by URL (that's the point: open the preview on a phone or send it to someone before publishing).

Saving a draft builds the site and deploys it. Not only the draft's own page: the deploy is the ordinary one, so everything the build produced goes to the target, the front page included. It has to -- the preview is a real address on the real site, and so is the answer a phone goes and asks for. There is no way to keep a draft off the target while its preview is expected to work. See Getting started → Pick a deploy target for what that means for a target that already holds something. 2. The CLI then asks: publish / schedule / keep as draft / back to editing. Publishing sets the date to that moment (scheduling asks for one instead), moves the post to its real URL and -- with a comments network configured (Mastodon or Bluesky, see Getting started) -- sends the announcement post that replies-as-comments hang off. 3. edit <slug> round-trips the stored post back to Markdown in your editor. A save that would drop content markdown can't express (an imported embed, a link card) warns and asks before proceeding.

A line reading //--more--// splits a post in two: 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. Without the marker a card is cut to fit a size budget, which lands wherever the budget runs out rather than on a sentence you chose. 4. unpublish <slug> returns a post to draft and deletes its announcement on the network (an announcement pointing at a dead URL helps nobody). The next publish gets a fresh date. delete <slug> moves the post and its media to trash/ -- restore <slug> brings it back. Trash keeps only the most recent deletion per slug. The same slug can exist in several years (backdating makes that easy); every slug-addressed command -- edit, delete, toot, publish, ... -- then first lists the matching posts (date, type, state, title) and asks which one you mean, so a delete can't silently land on the older post. A number picks, anything else cancels. 5. toot <slug> (Mastodon sites) or bluesky <slug> (Bluesky sites) (re-)sends the announcement for an already published post -- typically an imported one that never had one. An existing announcement is never overwritten.

A post's header can say more than the template offers. add prefills title, tags and type, because that is what every post needs; the parser accepts a few more keys, and edit brings back whichever ones the post already carries, so each can be read as well as changed:

• series: Name files the post into a series. A series with two or more published parts gets a listing of its own at /series/<slug>/ -- a series of one is just a post, and the listing appears when the second part does -- and with it a line in the index of series at /series/. The listing reads from part one: a long series is paged in reading order, /series/<slug>/ holds the first parts and /series/<slug>/page/2/, /page/3/… the ones after, so the "part 1 of 30" link on every post opens where the series starts. (Up to 1.7 a series of twenty parts or more opened at its last page instead, and its /page/N/ addresses held other parts than they do now.) A series whose name is too long to fit an address gets no listing; its parts still say which part they are, without a link. The build puts the series' name and "part 2 of 5" on each post in it -- and on each card of the series' own listing -- with the way to the part before and the part after -- within the series only, since a post's chronological neighbours across a whole archive are rarely what a reader wants next. Parts are ordered by date, which is what a series written in order needs; series_part: 3 is for the one written out of order or inserted afterwards. The draft preview answers the series question at writing time: a name with published parts shows how many and which part this would become, and a name no published post carries yet is called out as "a typo, or the first part?" -- so a misspelling doesn't quietly found a second series. check catches the older ones (below).

A number is a claim on a slot, not a label: the part is inserted at the position it names among the ones ordered by date, so a series whose numbers don't add up -- two parts both told 2, a number past the last part -- gives one of them a different place than it asked for. props says so where it happens, showing the number the post carries and, after it, the place the page will actually give it. Where the two agree, which is the ordinary case, only the number is shown. - link: gives the post a link card: the address it is about, drawn above the text. link_title: and link_description: are the words on it, and a post with no title: of its own is named by the card. It is a header key rather than a line in the body because a paragraph that is only a link already means something else -- an ordinary link in ordinary prose -- and because the card belongs to the post, not to a paragraph of it. edit writes all three lines back out, so a save cannot drop a card the author never touched. The address is a whole http:///https:// one, or one rooted at this site (/posts/2026/some-post/) for a card about another post here -- which is also the shape check --repair leaves behind when it straightens a relative link out of an import. - publish: yes publishes the post the moment add <file> writes it -- the date settled, the announcement sent, the site rebuilt -- the road publish <slug> --yes takes at a desk. Only the file route reads it; the wizard never publishes directly. Absent, or anything but yes/true/1, is a draft. - edits: <slug> makes the file not a new post but a new text for that post -- the save edit does, with every question it would ask turned into a refusal, because nobody is there to answer it. base: beside it is the digest ./blog.sh drafts --json or edit <slug> --json handed out with the text; when the post has changed since, the file is refused (changed) instead of undoing whatever happened in between. A draft may come without base:; a published post may not (base_required), and saving one rebuilds and deploys. What the new text leaves out is taken out: a paragraph, a picture or a rule its author removed is the edit, and a picture the text stops naming is deleted from the post's media. A picture the text names by a name the post already has is the post's own file -- so a new one sent under that name is not used (the answer says so in warnings); a picture is replaced by sending the new one under a name of its own. Taking everything out is not an edit: a file with no text under its header is refused (empty), as a new one is, because that is also what a program sends when it never had the text -- of a post that had a body; one that is a title and its tags, or a link card, which travels in the header, has none to begin with, and is saved. What the text leaves as it was is saved as it was stored -- the very block, with whatever an import put on it that markdown cannot say (a paragraph's kind, a video's provider) -- so an edit changes what was edited and nothing else. A block the text did change is made again from the text, and keeps what the text could not have said about it -- the kind an import gave a paragraph, the address a video was first at -- where the save can tell which stored block it rewrote: between two blocks kept as stored, the rewritten blocks are paired in order with the stored ones of their kind when there are as many of each. A paragraph inserted beside a corrected one makes two for one, and both are saved as written. What is refused as a loss (content_lost) is what the author never saw going, and it is one of two things. A block the text has no line for at all -- a second link card, a player from somewhere the engine does not know -- is lost by any save of that text: such a post is marked editable: false when its text is handed out, and editing it is for the desk, where edit asks. And a block the edit rewrote may have held more than its words -- a mention an import made of @somebody, small print: that edit is refused too, naming the thing, while the same post edited anywhere else is saved, with that block as it stood. This is how an app saves a post it opened (see Writing from a phone), and a way for a script to edit without the $EDITOR trick. - toc: true / toc: false overrides the table of contents. A post with four headings or more gets one on its own -- that is the length at which a reader starts scrolling to look for something rather than reading down. Say false on a post that has the headings but not the shape, true to force one below the threshold. - hero: true / hero: false decides whether the post's first usable image runs full width above the title, with the date moving into a byline under the picture. Without the key the post follows layout.hero for the whole site (Getting started). A 1px image is never lifted, and a post with no usable picture simply keeps the ordinary shape -- there is no second template to keep in step.

Two things the site says without being asked. Every card and every post page carries how long the post takes to read, counted at 200 words a minute -- the same figure ./blog.sh stats reports; a post too short to time says "under a minute". And the build writes a noindex /404.html in the site's own chrome, menu and search field included, so a dead end is somewhere to go on from. Under its sentence stand a search field of its own -- filled, where the browser runs scripts, with the words of the address that was not found -- and pills back to the front page, to the archive and to the index of tags; an address that names a year the archive has gets a pill straight to that year. The page is one file for every missing address, served by your host: it is written in the site's first language whatever language the address was in.

Backdating isn't part of that flow -- publishing means "now" -- but the frontmatter parser still honors a date: line you type in by hand (the template just doesn't offer one). To publish a draft into the past:

./blog.sh edit muj-post      # add a line between the --- markers:  date: 2019-11-17 10:00
./blog.sh publish muj-post   # -> "Date kept from frontmatter: Nov 17, 2019 10:00"

The date takes any format Time.parse reads and is interpreted in site.timezone. The post's URL year follows the date -- the JSON and the media directory move into that year -- and the auto-announcement asks for confirmation first when the date is more than a day off. A backdated post is ordered by its date, so it can skip the homepage and RSS entirely and land straight in the archive; the CLI says so when it happens. If another post already owns that year/slug combination, publishing refuses rather than overwrite it. (schedule is the opposite direction on purpose: it refuses past dates.)

Scheduled publishing: in the post-save dialog, choose [s] and enter the publish date and time directly -- the publish-scheduled cron then publishes the draft (toot included) once that date arrives, keeping it as the post's date. The standalone ./blog.sh schedule <slug> asks the same question, so either route works. The time you type is read in site.timezone (Getting started) -- worth setting before you schedule anything from a server, whose clock is usually UTC. A past date is refused (that would just mean "publish now", and publish is for that). Running schedule on an already scheduled draft cancels it; list shows scheduled drafts as [SCHEDULED].

Two kinds of post are published by that cron without being announced, and it says so per post, naming ./blog.sh toot <slug> for sending the announcement by hand: a post dated more than a day from now (a backfill -- an old thread given a page, a post imported and then queued -- reads as news in a live timeline), and a post that already carries an announcement of its own, which happens when it was published once, unpublished and put back in the queue. Announcing that one again would leave the first thread live with its replies while the post pointed at a second, empty one. Several posts falling due in the same tick -- after the cron has been down, say -- are published oldest first, in the order the queue was arranged in.

In the terminal

The CLI adapts to where it runs. In an interactive terminal you get arrow-key menus (digits still quick-select, typing a slug still works), single-keypress answers without Enter, colored state markers and a QR code of the draft preview URL -- after a save, and on [q] in a draft's properties -- point your phone's camera at the screen instead of retyping a token. A menu longer than the terminal is tall scrolls, showing your position in the list next to the hint; Page Up, Page Down, Home and End work in every list.

The screens hold still. Menus, the queue, the archive, a post's properties and every picker repaint over themselves instead of printing another copy on each keypress -- and not on the alternate screen, so the last screen and your scrollback survive. Resizing straightens a waiting menu, the queue or the properties screen on the spot; a picker or the archive browser keeps the size it opened with until you leave it.

Enter and Esc mean the same everywhere. Enter takes what the question offers -- the capital letter in [Y/n], the named [Enter] …, the row under the cursor. Esc leaves without doing anything: it never builds, deploys, opens the editor or writes a file, and in a question about a setting it keeps the current value. A question you type an answer into is read a whole line at a time, so there it is Esc and then Enter: the current value stays, and "publish when?" is left without a date.

The three question-and-answer wizards -- ./setup.sh, ./style.sh and ./import.sh -- keep the section you are in and the answers already given above the question, so a half-finished run says where you are.

Piped, scripted or cron runs get the plain line-based prompts unchanged, with no escape codes in the output. Colors honor NO_COLOR and TERM=dumb.

./blog.sh preview [<port>] serves the built site locally (default port 8000) when you want to look at it without deploying.

Properties and actions

./blog.sh props <slug> (in the wizard: pick a post, then v) shows everything about one post in one place -- state, type, tags, the pin, the announcement -- and offers the guarded actions:

• published: unpublish, (re-)announce, pin/unpin, rename the slug, review the old addresses that redirect here, delete;
• draft: publish (asked first -- with a network configured it announces too, which nothing takes back), schedule (or reschedule, or cancel the schedule), rename the slug, delete -- and the screen names the draft's preview address, with [q] for its QR code, so a draft can be read on a phone without opening it in the editor first;
• either: [e] opens the post's properties -- which series it is in and which part of it, its tags, its type, and the three flags (out of the listings, lead image, chapter list);
• either, once there is one: [v] restores what the post said before one of its recent saves.

Properties are what the post IS, not what it says, and until 1.7 the only way to change one was edit -- the whole article open in an editor to add a series somebody forgot. Worse, on a post whose blocks markdown cannot all write down (an imported embed, a link card that is not the first block) that edit asks whether it may drop them, which is a great deal of risk for one word of metadata.

[e] writes each answer as it is given and rebuilds once on the way out. Two of the rows are pickers rather than prompts, on purpose: the series row lists the series the site already has, with how many posts carry each, because a series typed a second time is a second series and check only notices afterwards -- and the type row lists the eight the engine knows plus the way back to letting the content decide, which is what a post with no type of its own has always done. The tags row prints the site's most-used tags above the line it asks for, for the same reason.

The lead image and the chapter list have three states, not two: on, off, and whatever the site does -- which is what a post that says nothing about them takes, and a different thing from saying no.

props <slug> --json prints the same screen as one object and exits: state, date, address, type, tags, series, the flags, which languages the post is written in, whether and where it was announced (announces says which of the six cases it is), the old addresses -- and actions, the keys the screen would offer this post, by name (publish, schedule, unschedule, unpublish, announce, pin, properties, rename, addresses, versions, delete). A program reads that instead of re-deriving the screen's rules, then calls the command it wants. A slug nobody has, or one that lives in two years, is refused as an object ("ok": false, not_found or ambiguous_slug) with a zero exit, the way add --json refuses; the slug is required, because an object for an answer means nobody is there to pick one.

Undoing an edit is what [v] is for. Every edit and every translate keeps the previous text first, up to ten of them per post, and [v] lists them newest first with the line under the cursor showing what that version said -- its title, or its opening words when it has none -- so the choice is made by recognising the text rather than by reading timestamps. The key appears only on a post that has been edited at least once.

Choosing one is itself undoable: the current text is kept as a version before it is replaced, so a wrong choice is one [v] away from being walked back -- which is why a single key confirms it. Only the text comes back -- images are not versioned, and the line above the list says so. The text of every language the version holds comes back with it; a language the post was given since is left as it is, and so is the address each language serves the post at. A version that will not parse stays in the list without a preview. Versions travel with the post into the trash and back out again.

Type and tags are shown here but edited in the frontmatter of edit, prefilled with their current values -- one keystroke away from the text they describe. The pin is the exception: it is a switch, not a value, so [c] flips it right here (the pinned: header line keeps working too). The pinned post is also marked [PINNED] in every list and picker, so it can be found without remembering it. A plain draft shows no time on purpose: a draft has none until publishing or scheduling gives it one.

Keeping a post out of the listings is the unlisted: true line in its frontmatter. The post keeps its ordinary address, its date and its redirects, and drops out of the homepage, the tag and type archives, the feeds, the sitemap and the search index; its page is noindex. It is the draft's hidden address, generalised to something finished -- for a post meant for the few people you send the link to. It is not a password: a static site hands over whatever is asked for, so anyone with the link can read it and forward it. If that is not good enough, the answer is not to publish it. Publishing an unlisted post announces nothing -- by hand or from cron, and --force does not open that door, because an announcement cannot be recalled once a server has it; to announce the post, take the flag off first. props says so on an unlisted post, and the line comes back with its current value the next time you edit, so the state can be read as well as changed.

Renaming a slug never breaks a link. The old address stays on the site as a one-page redirect to the new one, recorded in the post itself (former_slugs), so it survives edits, re-imports and full rebuilds. A rename costs one extra page per old address -- not a 404. Two things to know: unpublishing takes the redirects off the site along with the post (they return when it does), and deleting the post deletes its old addresses' redirects with it. Renaming a draft is free -- nothing is published yet -- but its preview URL changes, so share the new link. One consequence the redirect can't cover: feed readers identify posts by their URL, so a renamed post may appear once more as a new item in subscribers' readers. The redirect keeps every clicked link working; what a reader app shows is its own business.

Moving a post to another year -- editing its date across a New Year -- moves its public address the same way a rename does, and records the old one the same way. The link from before the edit keeps working.

Old addresses can also be given up, with [a] in the same dialog: it lists every address that redirects here and drops the one you pick. There is one situation where that is the only cure rather than a preference: if a NEW post has since taken an old address, the build refuses to overwrite a live page with a redirect stub -- correctly -- and says so on every build. The entry can never do anything again, and [a] marks exactly that entry as "taken by another post". Dropping any other one is a decision, not a repair: that link stops working for good.

The wizard menu lists six activities -- a new post, a post in hand, the scheduled-post queue, the archive browser, the trash and a rebuild -- not every command: publish, schedule, unpublish, delete and the announcement live in this dialog (and the draft dialog) instead of being menu items. Every CLI command still exists unchanged -- ./blog.sh unpublish <slug> works exactly as before; only the menu stopped listing it.

./blog.sh translate my-post --lang de

Or from the wizard, which is where the rest of the work happens: pick the post, and the crossroads that offers its text and its properties offers the languages too. With one other language it names it ([l] language: Deutsch); with several it opens a picker that says what is already written, what is only started, and what has nothing yet -- the same three states check --languages prints. The properties screen carries a languages row for the same reason. (As data the two say them in different words: props --json has written, started and none, check --languages --json has written, title_only and missing.)

The editor that opens holds a title and a body, and nothing else. That is the whole of what a translation may carry: the date, the tags, the series, the pin and the state belong to the POST and are true in every language at once, so they are changed with props or edit and never here. A translation cannot quietly disagree with the post it belongs to.

Save it and ./blog.sh rebuild builds every language the site publishes: the language in site.lang at the site root, the others under /de/, all in one tree with one copy of /assets/ between them.

The header also holds the address that language serves the post at. Left alone it is made from the translated title, once, and then stays put -- see Localization.

The post's own words come along as // lines the first time, so the text being translated is in front of you rather than in another window. The editor drops every // line on save, which is also why a translation left half-done cannot save the original as though it were this language's.

What a translation's text does not say is kept, as it is for the post's own: a block the new text left alone is saved as it was stored, with a paragraph's kind or a video's player still on it, and a block the text rewrote keeps them too. What the text cannot carry at all -- a link card, a player with no address to write -- is asked about before it goes; from a file it is refused (content_lost), and translate --json marks such a translation editable: false beforehand.

Publishing a post the site cannot show in every language it publishes is a decision, not an accident: the command line refuses it and names --allow-partial, and the wizard asks -- write the missing language now, or publish it as it stands. A site that has made that decision for every post says publishing.allow_partial: true in config/site.yml, and is neither refused nor asked (Localization).

Taking a language off a post is emptying the title and deleting the body. The post then looks exactly as it did before the translation existed -- which matters, because a half-empty translation would otherwise give that language a page with the wrong words on it. Two things of it are kept: the text as it was, as a version [v] restores, and the old addresses that text was owed, which go to the post's own list.

An address that belonged to a translation is kept with it. When two posts that were the same piece in two languages are made one -- the English post becomes the Czech post's translations.en -- the English post's address is still out on the web. Put into the post's own former_slugs it would lead to the post, which at the site's root is the Czech page. Written into the translation instead, it leads to the translated one:

"translations": { "en": { "title": "…", "slug": "the-old-slug", "content": [ … ],
                          "former_slugs": ["2019/the-old-slug"] } }

/posts/2019/the-old-slug/ then redirects to /en/posts/2019/the-old-slug/.

The merge has two more steps, and check between them speaks of neither. The English post is still in the archive, at the very address the list now names -- so check says the address is taken by a live post and offers to drop the entry or rename that post. Neither: the English post is what goes, ./blog.sh delete the-old-slug, and the entry is served from then on. Before it goes, copy any picture only it had into the media folder of the post that stays (media.nosync/<year>/<slug>/), under a name the translation's blocks then use: delete takes a post's media to the trash with it, and a translation shows files from the folder of the post it belongs to. Deleting a published post also takes its announcement down where the network allows it, as any delete does. The same list covers a translation whose slug: is changed -- in the header translate opens, or in a text an app sends -- on a post that is out: the address its page stood at is written into the list by that save, as a post's own old address is when it is renamed, and redirects to the new one in that language's tree. (A translated page has no year in its address and the list has no way to say one; there the old address is yours to keep, with redirect_from.) For the merge the list is written by hand, and nothing drops it: translate and an edit from an app carry it across, and taking the language off the post hands the list to the post itself, where each address then leads to the post.

Such an address is answered in two places and no others -- the site's root and that language's tree -- and only while the language is published: take the language out of site.locales and its old addresses answer nothing, which check says of each entry. check asks each tree about its own pages, as the build does. An old address another post's page stands at in one of them is reported with where it is taken and where it is still served; and one written into the lists of two languages leads, at the root, to the text of the language the file names first -- check names that too.

A post you have not translated is not hidden. It stays in the other language's listing and the link on it goes to the address the post really has, so the same words never stand at two addresses. The language switcher still offers every language; one with nothing of this post in it leads to that language's front page rather than to a 404. What is promised to a search engine (hreflang) is narrower on purpose: only the addresses that exist.

Pictures belong to the post, not to one of its languages, so they are added with edit and referred to from a translation. translate refuses an attachment rather than putting a file in one language's copy of a post whose media the other languages share.

1. Shoot a photo, upload it via any SFTP client into <repo>/incoming/ (setup: Getting started).
2. SSH into the server, ./blog.sh add, and write ![caption](photo.jpg) -- no path.
3. If the photo hasn't finished uploading yet, the CLI waits and re-checks on Enter instead of failing.
4. On save the photo is copied into media.nosync/<year>/<slug>/ and its incoming/ copy is removed -- an empty incoming/ means nothing is pending.
5. Editing that post later doesn't need the photo again: a bare filename is looked for in the post's own media.nosync/<year>/<slug>/ first and in incoming/ only after that, so a file that's already been saved resolves without any upload (and without being copied again).

iPhones photograph in HEIC by default, which only Safari can display. Attaching one stops the save with the exact conversion command -- or, with media.convert_heic: true in config/site.yml, the engine converts it to JPEG itself during the save (detected by content, so a HEIC named .jpg is caught too; AVIF, which browsers do display, is left alone). The simplest fix is on the phone itself: Settings → Camera → Formats → Most Compatible.

A photo's GPS position never reaches the site. Saving strips the place of capture from the file's metadata (media.strip_location, on unless config/site.yml turns it off -- the notes there say why); the camera, the moment and the orientation stay. ./blog.sh doctor --strip-location cleans photos saved before the engine did this -- the only thing doctor ever writes.

Video from the same phone is mentioned, not refused. The same setting decides the codec, and the save says one line when it matters: that a clip is HEVC (most browsers play it, the rest show an empty player), or that it is a QuickTime .mov (the video inside is usually ordinary H.264, but not every browser accepts the container). Both come with the ffmpeg command that fixes them -- re-encoding for the codec, repacking for the container, which copies the video across untouched. A third line is about neither: a video whose index sits at the end of the file, which is where a recorder has to put it, and which makes a reader wait for the whole download before the first frame appears. The same repack moves it to the front.

media: remux_video: true has the engine do that repack itself, when ffmpeg is on the machine -- index to the front, .mov to .mp4, the picture and the sound copied across untouched, about a second for a phone video. Every video and sound track comes across, not just the first of each, and so does the recording time; the metadata tracks an iPhone adds to a .mov do not, because an MP4 has nowhere to keep them. It is off by default, like the HEIC conversion, because it shells out to a tool the engine does not ship. Unlike the HEIC conversion it never refuses: no ffmpeg, or a repack that will not go through, and the post is saved with the file as it arrived and the sentence the author would have had anyway. A video in the wrong wrapper still plays for nearly everybody; a HEIC photo does not.

The post is saved either way; the only hard stop for a video is the per-file size limit, and a long 4K clip reaches that on its own -- a phone clip out of the share sheet runs about 1.3 MB a second, so the 24 MB default is roughly seventeen seconds of it. A longer one wants a smaller size chosen in the shortcut's own Encode Media step.

Handing over a whole file

Every step above is a conversation: the CLI opens an editor, waits for a photo, asks what to do with the draft. ./blog.sh add <file> is the same work with the conversation removed -- it takes a markdown file with the usual header, writes the draft, and returns. It never asks anything, so it is the route for a shortcut, a script or anything else running where nobody is at the keyboard. The file is read as the editor's buffer is: a line starting with // is a note to yourself and does not reach the post (//--more--// is the one that does, and a // inside a code fence is the code), and neither does a <!-- ... --> block.

./blog.sh add clanek.md

A bare name -- one with no slash in it -- is looked for in incoming/, so the file can arrive by the same upload as the photos. Anything else is a path and is used as given, relative to wherever you were standing. A file that came out of incoming/ is deleted once the post is written -- the photos already work that way, and an empty incoming/ is what says nothing is pending. A file outside incoming/ is never touched: on a Mac that is quite possibly the only copy. The rule is about where the file is, not how you named it, so ./blog.sh add "$PWD/incoming/x.md" tidies up after itself like any other upload.

Where the wizard would ask, this refuses instead, and writes nothing:

• a photo that has not finished uploading -- the wizard waits and re-checks on Enter; here there is nobody to wait for, so the missing names are printed and the post is not written. Upload them and run it again.
• an empty body, a file that is not text, a file this account cannot read, something that is not a file at all, an option the command does not have, or a second filename (one file, one post -- a name silently dropped is a post a looping script thinks it made).

It stops at the draft. The file says write this down, not put it in front of the world -- publishing stays a second command:

./blog.sh publish <slug> --yes

--yes answers the draft dialog with "publish" in advance. --json, which needs --yes beside it, prints the same object add --json does -- ok, slug, path, state, scheduled, date, url, deploy, warnings, the keys every action on a post answers with -- or a refusal with its reason as a code (not_found, already_published, publish_refused), and leaves with zero either way, for the reason add does: a phone throws away the output of a command that failed. --no-announce publishes the page and sends nothing to Mastodon or Bluesky; it works with or without --yes, and because nothing was attempted, ./blog.sh toot <slug> can still send the announcement by hand afterwards. (It does not travel into a scheduled publish -- the cron works from the post itself and will announce it when its date arrives; the run says so if you schedule under the flag.)

One question --yes will not answer 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. Two more it refuses rather than guesses: --yes needs the slug spelled out (without one, publish offers the drafts to pick from, and picking belongs with the preview in front of you), and it will not choose between two posts sharing a slug in different years -- it names the years and stops.

--json turns the answer into data -- one object on standard output and nothing else, so a caller can read it without parsing prose:

{
  "slug": "psano-v-posteli",
  "path": "/home/me/blog/content.nosync/posts/2026/psano-v-posteli.json",
  "state": "draft",
  "url": "https://example.com/draft/89260b63fb498e75/psano-v-posteli/",
  "deploy": "done",
  "warnings": []
}

Every key is always there. deploy is done when the site is already carrying the draft and pending when it owes an upload that the next scheduled run will finish -- the difference between "open this address now" and "open it shortly". warnings collects everything the run said for itself, which on this route is the only place to hear it: a photo over the size limit, a video whose container some browsers refuse, a HEIC that was converted. url is empty rather than half an address when the site has no base_url yet, and the reason is in warnings. The exit code is 0 or 1, nothing else. A refusal answers in the same place and leaves with zero too, as a different object -- ok, error, message -- because the status answers a question the object cannot: whether an answer arrived at all. Only a flag the command does not have and a second filename fall outside this, and those end in prose on standard error.

A post sent from the phone itself

This page and its shortcut are on their way out. Native apps for iOS and Android are in preparation; they reach the engine over the same SSH (Over SSH, from an app) and need neither. 1.11 removes /write/ -- the page and everything published under that address -- the SendPost shortcut and the publish.txt and drafts.txt requests described below. In 1.10 everything in this section works as written -- but for the link that opens a draft (Editing a draft from the phone) -- and nothing is being added to it. Two things stay, because the apps use them as the page does: the receiver itself, scripts/receive.sh, and the receipt: line of a delivery, which is what makes a delivery that arrives twice one post.

write: true publishes a page at /write/ to write the post on: a title, the text, tags, and photographs each with its description. It keeps what is typed in the browser, so closing the tab in a tunnel loses nothing -- the text in localStorage, the bytes of the pictures and videos in IndexedDB, which holds hundreds of megabytes where localStorage holds five. The page is marked noindex and holds no secret of its own -- what sending needs is the key, and that lives in the shortcut on the phone. Add it to the home screen and it opens as an app -- that is what the manifest among the published files is for.

It also carries a content policy of its own, which is the one thing it could not inherit: the page is copied onto the site as a file and never goes through the layout every other page is rendered by, so until 1.7 it had none. Now it does, and it is a short list -- scripts and styles from the blog, pictures and video only as the page's own data: and blob: bytes, one place to connect to (itself, for the receipt), the preview frame same-origin, no form action at all, and scripts never inline. A reply arriving in the address bar has nowhere to reach even if it carried something that ran.

The page is the same file on every site; what is this site's the build writes beside it as write/site.js: the short name and claim for the header, the palette from colors: so the page is dressed like the blog, the favicon, and every tag the blog has used, with its count of all time and of the last twelve months. The tags are offered as they are typed: with nothing typed yet, what the blog has tagged in the last year, most used first -- not the most used of all time, which on an imported archive are the places it came from; then whatever begins with or contains the letters so far, searched across every tag. So a tag is tapped rather than typed, and typed as it was before instead of the blog growing a second spelling of it.

The page speaks the blog's language, site.lang, whatever the phone is set to; the browser's is used only where there is no site.js, or where the blog's language is one the page has not been translated into. Above the text sits a row of marks -- bold, italic, strikethrough, code, link, heading, quote, list, numbered list, code block. A paired mark wraps what is selected, and a second tap takes it off; with nothing selected it puts the pair in and leaves the caret between. A line mark goes to the start of every line the selection touches, and comes off the same way. The link mark reads the selection, widened to whole words: an address -- https://…, or a bare domain, which gets its https:// -- becomes a link with the words left to type; words become one with the address left to type.

A picture does not travel as it is. The page draws it through a canvas first -- 2560 px on its long edge, JPEG at quality 0.88 -- which is what makes a post of four photographs fit under the ceiling at all, and it is why the file arrives as vlak-v-chocni.jpg whatever the phone called it: the name is folded to ASCII so the markdown can name it without escaping, and a second picture folding to the same name gets -2. A picture this browser cannot decode -- a HEIC outside Safari -- is passed through untouched under its own extension. Send the original by SFTP and use add if the re-encode is not what you want.

A video goes the same way as a picture -- the same button, the same card, the same description -- and into the text as !![description] (clip.mp4), two marks where a picture has one. Nothing on the page shrinks it: it travels as it is, and the blog says on arrival what it says of any phone video (see below). What limits it is the receiver's ceiling on one delivery, BLOGSH_MAX_MB (24): the page carries that number in site.js, says under the pictures what happens to a picture, what to a video and how much the server takes, and turns the batch line red the moment the post outgrows it -- before the phone spends the upload finding out. The first tap on Send stops there and says it; a second tap sends anyway, because the page's number is the build's and the server's may have been raised since. The receiver reads the variable in its own environment, the forced command's, and the build reads it in the build's; raise it in both places or in neither.

Preview, under the text, shows the post as the blog would show it -- in the blog's own stylesheets, which site.js names, with the pictures in their places. Near enough, not exact: the engine renders the real thing, and the draft's preview after sending is that. What it is for is seeing the shape of a post before it leaves the phone.

Pressing send hands the files to iOS: one for each picture, and one for the text. Nothing is packed for the server: it takes files, not archives. A browser that refuses to hand files over at all gets the post saved as one archive instead -- a net, so a post written on the way home is not lost to a browser that will not share it, rather than a road this page offers. /write/ is for a phone; on a phone the files go over.

Under Chromium the text is called <name>.md.txt. Chrome and Edge, on Android as at a desk, share from a page only a file whose extension is on their own list, and .md is not on it while .txt is; a .md is refused before any sheet opens, and canShare says true all the same. The page tells Chromium by navigator.userAgentData and names the text accordingly; the receiver puts the .md back, so whatever takes the files on such a phone passes them on under the names it was given and nothing else. WebKit keeps .md, and must: iOS reads a .txt as text rather than a file and hands the shortcut its first line for a name. A browser the page misjudges gets a second tap -- the refusal says so -- which sends the text as .md.txt. Note what the list also leaves out: .zip, .heic and .mov. A video from an Android phone is .mp4 and goes; the saved archive never went anywhere but a shortcut anyway.

One shortcut, run twice, because the run that receives the files may not open an SSH connection. A shortcut started from the Share Sheet runs in Shortcuts' background runner, whose only screen is a banner; Run Script over SSH asks for a screen there -- the host prompt, the first-run privacy question -- and is refused with "This action could not be run with the current user interface", before any connection is made. The action that would hand the run over to the full app, Continue in Shortcuts App, is no longer offered. A shortcut started from a URL, on the other hand, always runs in the app. So the same shortcut runs twice: from the Share Sheet it packs the files into one batch, writes it to a file and opens a URL that names itself; from that URL, with nothing handed to it, it reads the file back and sends it. The two runs are told apart by the one thing that differs between them, whether there is a Shortcut Input. One shortcut per blog.

"Show in Share Sheet" on, accepting Images and Files; "If there's no input": Continue -- not Stop and Respond, because the second run has none and has to go on. Then:

1. If Shortcut Input does not have any value -- the second run. Inside it:
   1. Get File incoming/batch.txt from the Shortcuts folder in iCloud Drive, without the document picker. A folder chosen in the action, not a variable; see the warning below.
   2. Run Script over SSH with that file as the Input; the script is the receiver, or the wrapper that reaches it.
   3. Base64 Encode the Shell Script Result (Line Breaks: None, if the option is offered; the page copes either way).
   4. Delete Files with the File from Get File, Immediately Delete on. Without the switch it asks before every post; without the action a batch already sent would wait for the next run that finds nothing to share, and go out a second time.
   5. Text: https://YOUR-BLOG-URL/write/#b= followed by the Base64 Encoded variable, with nothing between them.
   6. Open URLs with that text.
   7. Stop and Output the result, or Stop This Shortcut -- the second run ends here and never reaches the loop below.

End If. 2. Repeat with Each over Shortcut Input -- the first run -- and inside it: Get Name, Get File Extension, then a Text holding mov mp4 m4v MOV MP4 M4V and an If Text contains File Extension. Inside the If: Encode Media the Repeat Item with Size 1280x720, and Set Variable item to Encoded Media; in Otherwise: Set Variable item to Repeat Item. After End If: Base64 Encode item, a Text of three lines -- Name.File Extension, Base64 Encoded, . -- and Add to Variable batch.

The If is what makes a video from the phone fit: a clip from an iPhone, 32.5 MB of HEVC, came out of Encode Media at 5 MB of H.264, in the QuickTime container it arrived in, so the extension the batch names is still right. A picture takes the Otherwise branch untouched. The page cannot know the shortcut does this, so its red line for a video measures the original; send anyway, and the answer says what arrived. 3. After the loop: Combine Text batch with New Lines. 4. Save File the combined text to iCloud Drive, into the Shortcuts folder, Ask Where to Save off, subpath incoming/batch.txt, Overwrite If File Exists on -- the same file step 1 reads back. 5. Open URLs: shortcuts://run-shortcut?name=SendPost, where SendPost is the shortcut's own name, spelled as the library spells it. Rename the shortcut and this line has to change with it; a name without spaces or punctuation saves percent-encoding it.

It can be imported instead of built: SendPost, signed so that anyone may import it. It arrives called SendPost, and the last Open URLs opens it by that name; rename it and change the name there to match. Then fill in what is yours. In Run Script over SSH: the machine you log into (a host name or an IP address), its SSH port, the user, and the path to scripts/receive.sh or the wrapper that reaches it. In the Text: YOUR-BLOG-URL is the address the site is served at, base_url in config/site.yml. The SSH action carries no key; pick or generate one there and put its public half on the server, as the key line below shows.

⚠️ Pasting actions between shortcuts rewires them. Shortcuts reconnects a pasted action's inputs to whatever stands above the place it lands. A Get File copied in this way came back reading from a Text, then from If Result, then from Shortcut Input -- which is empty in the second run, so it read nothing, the SSH action sent nothing, and the server answered empty_input for a batch that was whole. After any paste or move, check that Get File still reads from Shortcuts, and that the SSH Input and Delete Files both name the File it produces.

It runs on a Mac as well. The Shortcuts app there has the same shortcut through iCloud, Safari's Share Sheet offers it, and the terminal runs it: shortcuts run SendPost with a batch.txt in the Shortcuts folder sends that batch and prints the address it would have opened -- which is how the sending half is tested without a phone. /write/ itself is still made for a phone.

Base64, not URL Encode, and not for taste: Shortcuts reads a reply that is JSON as a Dictionary and then refuses to hand a Dictionary to URL Encode -- "couldn't convert from Dictionary to Text" -- on exactly the replies that matter, the refusals. Base64 Encode takes anything. (The page also still reads a percent-encoded reply after #r=.)

Base64 Encode, the Text and Open URLs carry the answer back to the page. It opens with the reply after #b= -- a fragment, so it never leaves the browser -- and says what the server did: the pictures it kept, the draft's preview address or the post's public one, the command that publishes a draft from a keyboard, and a refusal in the reader's language where the page knows the code, in the server's own words where it does not. A post the server took is cleared from the device; a refusal keeps everything, so it can be mended and sent again.

And the page asks, as well as waiting. That road back has one break in it that nothing on this end can mend: a page kept on a phone's home screen runs with storage of its own, so a reply that arrives as a URL opens in the browser, where the draft it is about does not exist -- and the draft stays on the home-screen copy, looking unsent. So the page picks a name for its answer before it sends anything (receipt:, sixteen hexadecimal characters, written into the markdown), and the build leaves a small JSON file at /write/r/<receipt>.json saying 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, a player that was not found. The page draws those the way it draws the answer that comes back through the address bar, because the phone is the one place with no terminal to read them in. Only what was said about the POST: the file is served to anyone who has the sixteen characters, so what the run says about the SITE afterwards (a missing base_url, whatever the rebuild warns about) stays out of it. The page asks for it every three seconds for fifteen minutes, and says so if it never comes; a page reopened later asks once more, and shows the answer or says it did not come. Whichever answer arrives first is the one that is shown.

The file is written by the BUILD, which is what keeps it true: publish the post and the next build says published and gives the public address; delete the post and nothing generates the file, so the sweep takes it away. It exists only on a site that serves the page, and only for a post that asked for one.

Publishing from the phone. The answer for a draft carries a Publish button, and it sends one file called publish.txt holding the slug -- down the same connection, through the same shortcut. The receiver knows that shape: exactly one file, called that, and it runs publish <slug> --yes --json rather than storing anything. The slug is checked as hard as a filename is, because it becomes an argument to a command: a leading dash is a flag, and anything outside a slug's own alphabet is refused here rather than explained by whatever it hits. The page then asks the same receipt again until it says published.

Editing a draft from the phone

This is what an app does: it asks the blog for its drafts (drafts --json) and sends the text back with edits: <slug> and base: <digest> in its header -- see Over SSH, from an app, and the header keys for what such a save keeps and what it refuses.

The page was given a link for it too, Open a draft from the blog, which sends one file, drafts.txt, through the shortcut and waits for the list of drafts in the address. Tried on a tablet it loaded nothing, and it is not being repaired: the page is frozen and leaves in 1.11.

A delivery that arrives twice is one post. The receipt is minted once per send, immediately before the files it names are built, so two deliveries carrying the same one are the same send arriving twice -- which is what a connection that breaks after the bytes have gone but before the answer comes back produces, and both the shortcut and the Termux script retry. The second delivery updates the post the first one wrote instead of founding another beside it -- and that holds when the retry arrives while the first is still being written, because writes carrying a receipt take turns. Once the post is published, a late retry stops updating anything at all: it is answered with the published post, at its public address, and the file is left exactly as it stands. The copy the phone is still holding was made before publishing happened and cannot know about it, so letting it write would put the post back to draft -- with a new address, a new date and the announcement pointing at nothing. Pressing send again is not that: the page mints a fresh receipt each time, so a second send is a second post. A delivery carrying no receipt at all -- anything hand-rolled -- has nothing to be recognised by, and a repeat of one is two posts as it always was.

One connection carries the post however many photographs are in it, which is the point: connections are the scarce thing, not bytes. The first run in the app asks whether the shortcut may send its items to the host -- answer Always Allow; that is the very question the background runner could not put on screen.

The page that sent the files sees the share end in an abort -- that is how the hand-off to the app looks from a web page, not a failure -- so it says the files have left. The answer arrives when the second run opens the page again with it.

The order inside the batch matters, because the markdown arriving is what makes the post and everything its text names has to be on the server by then. The app puts the markdown last for exactly this reason. Get it wrong and nothing breaks -- the engine answers missing_images and writes nothing, and sending the text again once the pictures are up is all it takes.

Draft or public is decided when the post is sent. The page has a switch, Draft or Publish now; Draft is the default and writes nothing. Publish now writes publish: yes into the front matter, and add then takes the road publish <slug> --yes takes at a desk: the date is settled, the announcement goes out to the networks the site has configured, the site is rebuilt and deployed, and the answer carries the public address rather than a draft one. There is no third state: a post that is public is announced, on a phone as at a desk. The key is only read by add <file>; the wizard never publishes directly.

add <file> wants the file to be on the server already. receive.sh is how it gets there: the whole post down one connection. Each file is a name on its own line, its base64 after it, and a line holding a single . to say that was all of it -- then the next name.

{ for f in photo.jpg post.md; do
    printf '%s\n' "$f"; base64 < "$f"; printf '.\n'
  done
} | ssh blog ./scripts/receive.sh

One connection, not one per file. It was one per file once, which is simpler and does not work: a server worth running drops new SSH connections that arrive in a rush, and a common setting allows about four a minute. A post with three photographs sat exactly on that line and one with nine had no chance -- the sender saw "could not connect to the SSH server" and the pictures that never arrived were missed by nobody, since each connection answered for itself alone.

Every name in the delivery is read before a single byte is written, so a batch refused on its fifth name leaves nothing behind from the first four.

The closing dot is not decoration. A connection that drops halfway ends the same way a finished one does -- the receiver reads to the end of the stream either way -- so half a photograph arrived, decoded into half a picture, and was answered with ok. Without the dot the transfer is refused as truncated and nothing is stored.

A shortcut on a phone sends a whole post that way -- every picture, then the markdown, down one connection -- and the markdown last, because the markdown arriving is what makes the post. Everything its text names is already staged under the name it uses, so there is no other signal to send and none is needed. The answer to a picture is {"ok":true,"stored":"photo.jpg"}; the answer to the markdown is the same JSON add --json gives.

⚠️ The shortcut has to SHOW the answer, or every refusal looks like it worked. A refusal leaves with zero -- deliberately, because iOS Shortcuts discards the output of a remote command that failed, and the reason is the whole point of the answer. The cost is that Shortcuts then reports a tick for a refusal exactly as it does for a post. End the shortcut by opening the page with the answer, as the second run above does, or with a Show Content of the SSH output. The reply is one JSON object per file, so read it whole: a picture answers "ok":true and the name it was stored under, a refusal answers "ok":false and names the reason, and the post that was written answers with its slug (and, since 1.10, "ok":true like every other answer). Without that, a shortcut whose Input field is empty connects, waits out the thirty-second deadline, is refused for empty_input, and shows a tick -- which is a slow, silent way to learn nothing.

The exit code answers a different question from the JSON. Zero means an answer arrived -- read the object, which says "ok" and, when that is false, names the reason. Non-zero means there is no object to read at all: the script was killed, or the shell never got to run it. Everything the receiver can put into words leaves with zero, and that includes the refusals about the installation rather than the delivery -- no incoming/, no engine, a ceiling that is not a number. Which kind of trouble it is, the error code says. (iOS Shortcuts discards the output of a remote command that failed, so a refusal that exited non-zero reached a phone as a bare status with its reason gone -- exactly when the reason was the point, and those refusals are the ones a new install meets on its very first delivery.)

The body has a deadline of its own, BLOGSH_BODY_SECONDS (600): a delivery that has not finished by then is dropped and, if the sender is still listening, told timeout; it is set where BLOGSH_MAX_MB is, below. Two files under one name in one delivery are refused (bad_name) rather than one silently replacing the other, every body is decoded before any file is written, so a refusal on the third picture leaves nothing of the first two behind, and a blank line after a complete delivery is not held against it. When the engine itself does not answer in JSON -- no env.sh, no ruby, a configuration that will not parse -- the receiver answers for it with engine_failed and the words the engine printed, and every delivery ends with status 0 once an answer has been given -- a ceiling that is not a number (bad_limit) included.

Deliveries are taken in one at a time. From the first file of a delivery landing in incoming/ to the engine having taken them out again, a second delivery waits: incoming/ is one folder, a picture is known there by the name it was sent under, and two phones -- or one app sending two posts -- both call their first picture 01.jpg. The one that waits does so for up to BLOGSH_TURN_SECONDS (300, set where the other two are) and is then told busy, with nothing of it stored; send it again. A delivery that died mid-way does not hold the next one up.

A delivery that goes wrong halfway can simply be repeated. Pictures wait in incoming/ until a text names them, so a refused post leaves them where they are and sending it again finds them -- nothing has to be uploaded twice.

Nothing new listens on the network. It travels over the SSH the server already has, and the key it travels on wants a forced command:

restrict,command="/path/to/blog/scripts/receive.sh" ssh-rsa AAAA... phone

The key has to be RSA. Shortcuts' Run Script over SSH does not speak ed25519 and says nothing when it meets one -- the run simply fails.

What a stranger chooses is a filename and some bytes, so that is what is checked. A name carrying a path or a backslash, beginning with a dot, empty, longer than a filesystem will take, or holding a control character is refused (bad_name) and nothing is written. What arrives is bounded before it lands rather than weighed afterwards: BLOGSH_MAX_MB (24) is a ceiling on reading, so a sender costs that much and not whatever they felt like sending. The number is measured on the encoded stream, not on the files -- base64 is a third larger -- so a 24 MB ceiling takes about eighteen megabytes of photographs; the page's legend says the same, and the red line it draws counts the encoded size. A delivery that overshoots is read to its end into nothing -- up to four times the ceiling -- and then refused, so the sender finishes and hears too_large; refused the moment the ceiling was reached, a phone with megabytes still to send sat on "running" with no timeout to save it, and the answer never arrived. Beyond that bound the channel closes, and a hostile sender costs reading, never storage. And the post itself is handed to the engine as untrusted, so a picture may be named only by a bare filename -- ![](/etc/passwd) is refused (bad_reference), because otherwise it would read that file into the post and publish it.

Raising the ceiling is two settings, not one. The receiver reads BLOGSH_MAX_MB from its own environment -- the one the forced command runs in: put it in the key's line, command="BLOGSH_MAX_MB=64 /path/to/blog/scripts/receive.sh", or, where the command is a wrapper that enters a container, in that wrapper (docker exec -e BLOGSH_MAX_MB=64 …). The page at /write/ never asks the server; it shows the number the BUILD saw in BLOGSH_MAX_MB when it wrote site.js -- so set the same value where the build runs (env.sh) and rebuild, or the page will warn at 24 while the server takes 64, or say nothing while the server refuses. Unset on both sides, both say 24.

There is deliberately no archive. An earlier design took a ZIP and unpacked it here; three adversarial audits found blocking faults in three successive rewrites of it, and nearly all of them lived in the unpacking -- entries that were symlinks, names that collapsed onto each other, a bomb that wrote gigabytes from megabytes, a half-failed extraction that published a truncated photograph and reported success. None of that can be expressed when there is nothing to unpack.

Three rules follow from "nobody is at the keyboard":

• A question the dialog asks is a flag. The slug typed back to confirm a delete is --yes; the date the schedule dialog asks for is --at; "shift the rest of the queue forward?" is --compact; "rebuild and deploy now?" is --rebuild; "publish it though one of the site's languages has no text for it yet?" is --allow-partial. Without the flag the answer is no -- a program that did not say it did not mean it. (On a site of more than one language that last one decides whether anything can be scheduled or published at all before it is translated: without it both answer partial_translation -- unless the site itself says publishing.allow_partial: true, which props --json shows as languages.allow_partial, and then neither does.)
• Those flags are for --json only. delete <slug> --yes without --json is refused: at the terminal the dialog is there to ask, and a flag that silently skips a confirmation is how a shell history deletes a post.
• A post is named by its slug, and never guessed. The same slug in two years is refused as ambiguous_slug where the terminal would show both and ask; list --json carries the year so a program can tell them apart, and will be able to name one. A slug no post has is not_found.

deploy in an answer is done when the site was rebuilt and deployed, pending when the rebuild was attempted and the next scheduled run owes it (the .deploy-pending marker), and skipped when the action does not rebuild unless asked and --rebuild was not given. The actions that rebuild without asking at the terminal -- publish, unpublish -- do so here too; the ones the terminal asks about -- delete, restore -- wait for the flag, so a program making three changes can rebuild once.

What a refusal's message says is the sentence the terminal would have printed, in the site's language; the error code is the same in every language and is what a program should switch on. A new code may appear in a later version; an existing one does not change meaning.

A command that writes a post -- props --set, --drop-address, --rename and --restore-version, schedule, publish, unpublish, delete, restore, toot, bluesky, a move in the queue -- answers busy while another run holds the archive: a build, the scheduler, another of these. Nothing was written, and the same request a moment later is the way through. (A text sent as a file is not among them: it says which version it edited and is refused as changed.)

An action on a post answers with the same nine keys whichever action it was -- ok, slug, path, state, scheduled, date (null for a plain draft), url, deploy, warnings -- and with what its row of the table adds. add of a file through a delivery answers that way too, for a new post, an edit and a translation alike. Two answers are about something other than the post and have a shape of their own: delete says where the post went (trash, announcement_kept, deploy, warnings), and a move in the queue answers with the queue.

One thing about types, for a consumer written in a language that has them: a post's year is a string wherever a post is named -- it is the folder the post is kept in, and what tells two posts of one slug apart -- and a number only in on-this-day, which counts with it.

Over SSH, from an app

A program on another machine -- the blog.sh app on a phone, a script -- reaches the engine over the SSH the server already has, on a key of its own with a forced command, the way the phone's shortcut does:

restrict,command="/path/to/blog/scripts/remote.sh" ssh-ed25519 AAAA... app

A request may also say which language its reader reads, {"args": ["doctor"], "lang": "cs"}. A blog speaks its own language, and an app in Czech showing an English blog's diagnosis would show English; with lang, check and doctor -- the two answers that are sentences for a person, and that build nothing -- are said in that language, if the engine ships it, and so is what pair itself refuses (device_unknown, busy). What the door refuses before the engine is run it says in English, as it always has. Every other command answers in the blog's language as before, because a command that may rebuild the site must not be handed another one. A language the engine does not have is not an error: the answer is then in the blog's own. The code is the bare one a locale file is named by, in lower case -- cs; what a phone calls its language (cs-CZ, cs_CZ, CS) is cut down to that by the sender, or it counts as a language the engine does not have.

scripts/remote.sh allows three words as the SSH command and nothing else. run runs one engine command: its argv arrives on standard input as one line of JSON, {"args": ["props", "venku", "--set", "tags=louka, les"]} and a newline -- the line ends the request, so a sender that cannot close its side of the stream is answered all the same -- word by word, so nothing is ever parsed as shell and a value with spaces or diacritics is one word on both ends. Before the engine sees it, scripts/remote.rb checks every word: the command has to be one a program may run (version, list, drafts, edit, translate, props, queue, schedule, publish, unpublish, delete, restore, rebuild, empty, toot, bluesky, stats, on-this-day, check, doctor, and pair for its list and the caller's own way out), each flag one that command has in its --json form, every positional word a slug, and no word may hold a control character or be longer than 4000 bytes. A slug here is a name as a file may have it and a reader would read it -- letters and digits of any alphabet, _, . and -, not starting with . or - -- which is wider than what the engine itself makes (lowercase, digits, hyphens) because an import keeps the names the old system gave: a post list hands out can be asked for by that name. --json is added when it is missing, so the answer is always an object -- and with it edit and translate open no editor: they hand the text out, and the changed text comes back as a file through deliver. What is not on the list is what asks a question, writes outside the archive or reaches a network on somebody else's account: add (a post arrives through receive), export, preview, browse, check --repair, doctor --online and --strip-location, the wizard -- and of pair everything but --list and --revoke with nothing after it: showing a code opens a way in, and a device named after --revoke is somebody else's (see "Letting an app in by a code"). receive is the delivery scripts/receive.sh takes -- pictures and a markdown, or a publish.txt or drafts.txt request -- for the same key. deliver is the same delivery for a sender that cannot close its side of the stream: it ends with a line saying end instead, which scripts/remote.rb reads up to and hands to receive.sh whole, so every check the receiver makes is made; a file may not be called end, and a delivery over twice the receiver's ceiling is dropped on the wire (too_large) before the receiver measures it exactly. version --json says the ceiling (max_mb), so a sender can weigh a delivery first.

Every answer to run is one object and the status is 0, for the reason the receiver gives. A delivery -- receive or deliver -- is answered as the receiver answers, with an object for each file, one after another: a line for every picture stored or refused, then each post that was written, printed over several lines. That is neither one JSON document nor a line apiece; a reader takes it object by object, by its braces.

A request that is not JSON, holds a word the whitelist refuses or is over 64 kB is refused as one (bad_json, bad_args, unknown_command, too_large), one that never arrives as empty_input, a connection that says none of the three words as no_command, and the engine answering in prose -- no env.sh, a configuration that will not parse -- is wrapped as engine_failed with its words: the end of what it said, or, where it died of an exception, the line that names the error -- and how it left, its status or the signal that ended it (a build killed for memory reads "ended by signal 9 (KILL)"). Two clocks answer timeout: the request's one line has BLOGSH_LINE_SECONDS (30) to end once it has begun, and an engine still running after BLOGSH_RUN_SECONDS (1800) is stopped with whatever it had started -- asked to end first, then ended, the whole of what it had run with it. A delivery through deliver is held to the same: the whole of it has the receiver's BLOGSH_BODY_SECONDS (600) from its first byte, however it trickles and wherever in a line it stops; it is measured against the ceiling as it comes, not line by line; and the receiver it is handed to has BLOGSH_RUN_SECONDS like any engine. Each of the three is a whole number of seconds, of eight digits at most, with spaces around it ignored; anything else -- a word, a zero, 30m -- is refused as bad_limit, naming the variable, rather than read as no time at all. An engine that a signal ended -- a build killed for memory on a small server -- is engine_failed naming the signal, to a request and to a delivery alike, and an answer is always valid UTF-8 whatever the engine printed. Unlike the shortcut's key this one may be ed25519; the forced command runs in the same environment receive.sh does, with the same BLOGSH_MAX_MB for deliveries.

Sending again. A connection can break after the request has gone and before its answer is back, and the sender cannot tell which side of the engine that was. What a second send does:

• A question -- version, list, props, queue, drafts, edit, translate, check, doctor, stats -- changes nothing and can be asked as often as it takes.
• publish, unpublish, delete, restore and schedule --cancel are answered the second time by the state the first one left: already_published, already_draft, not_found, not_scheduled. That refusal is the news that the first one arrived.
• A new post delivered twice is two posts -- unless its file carries receipt:, a name the sender makes up once for the post (sixteen hexadecimal characters), and then the second delivery is the first one arriving again and updates the post it wrote (A delivery that arrives twice is one post). The line is the apps' as much as the page's, and stays when /write/ goes.
• An edit or a translation -- a file saying edits: and base: -- delivered twice is changed the second time: base: is the digest of the post's file, and the first delivery changed it. The answer to a save does not carry the new digest, so edit --json (or translate --json) is asked again before the next save, and after a changed whose cause may have been the sender's own first try.
• After timeout on an action the engine was stopped where it stood, and the action may be half done: a publish written to the archive and not yet on the site answers already_published from then on, while its address is a 404 until the site is built -- by the next scheduled run, which owes it, or by rebuild --json. Ask props what state the post is in, and rebuild if it is out.

The forced command runs in the account's non-interactive shell, which reads none of the files a terminal session reads -- so a Ruby that lives under rbenv or Homebrew is not on its PATH, and the engine refuses the system's old one. Put the path in the key's line, the way BLOGSH_MAX_MB goes there: command="env PATH=/home/me/.rbenv/shims:/usr/bin:/bin /path/to/blog/scripts/remote.sh". (env in front makes it a line every login shell runs: PATH=... script alone is sh's way of saying it, and an account whose shell is csh or tcsh takes it for a command's name.) A path with a space in it is single-quoted inside the double quotes; the app writes the line that way itself.

Where the blog lives in a container, the forced command is the one that enters it, and the word SSH was asked for -- which the script reads from SSH_ORIGINAL_COMMAND -- does not cross into the container by itself. Hand it over as the script's argument, which it takes the same way:

restrict,command="sudo docker exec -i blog /app/blog/scripts/remote.sh \"$SSH_ORIGINAL_COMMAND\"" ssh-ed25519 AAAA... app

-i is what carries the request in; the account needs to run that one command without a password. The app writes this line too, from the blog's place and the command it is reached through. Keep the quotes around $SSH_ORIGINAL_COMMAND: the word is handed on as one argument, and split into several, what the caller sent would be read as more than the command -- as the word a device's line says of itself, below.

Letting an app in by a code

Writing that line by hand stays what it is, and for whoever would rather not there is a second way beside it:

./blog.sh pair                    # shows a code and waits for the app
./blog.sh pair --list             # the devices let in this way
./blog.sh pair --revoke 2         # takes one out: its number, name or fingerprint from --list

--list numbers the devices, and --revoke takes that number, the device's name (quotes or no quotes: --revoke motorola edge 70 fusion) or its fingerprint. With nothing after it, somebody at a terminal is asked which one, and nothing goes without a yes.

pair draws a QR code in the terminal (and prints the same thing as a line of text, for an app with no camera to point). The code wants a window of some sixty columns by thirty-five rows, which is more than a terminal opens with, so a window too small is asked to grow first; one that does not is told how large the code is, and the line of text is there either way. The app reads it and is connected; nobody types an address, a user name or a key. What the code holds is where to connect -- the address, the port, the account -- the fingerprints of this server's own SSH keys, so the app knows it reached this machine, and a key that is good for one thing, once, for ten minutes: handing in the public half of a key the app made itself. The engine then replaces the code's line in ~/.ssh/authorized_keys with an ordinary one for the app's key, held to scripts/remote.sh like a line written by hand. The key the app lives on never leaves the device, and the one that was on the screen opens nothing once it has been used.

A device's line says one thing a line written by hand does not: whose it is. Its command ends .../scripts/remote.sh' --device=<fingerprint>, the fingerprint of the key on that same line. sshd tells a forced command nothing about the key that was used, so that word is how one device is told from another -- and the only thing it is told by: not by anything a request says, and not by the environment a session arrives with. A device let in before lines said this gets the word the next time ./blog.sh pair is run at a terminal -- --list is enough -- and nothing else on its line moves. (By the account itself: under sudo the lines are left as they are, because a file replaced by root is root's, and sshd reads it as the account.)

What pair does to authorized_keys, since that is the file that decides who may log in:

• It writes only lines that begin restrict, and whose command= names a script of this installation: restrict,expiry-time="...",command= for a code that waits, restrict,command= for a device. What an app hands in is taken only if it is exactly one ed25519 public key.
• Where authorized_keys is a link -- kept with your dotfiles, say -- the link stays a link and the file it points at is the one rewritten. The file keeps who may read it (one you made read-only stays so) and is never left writable by anybody else.
• It touches only lines it wrote itself, known by the comment that ends them (blog.sh:<device>, and blog.sh-pair:<id> while a code waits) together with this installation's path. Every other line -- a key of your own, another blog's devices -- is written back as it was.
• The file as it was before each change is kept beside it as authorized_keys.blog-sh.bak.
• With a code closed again, or a device come and gone, the file is byte for byte what it was: carriage returns on lines that are not pair's stay, and so does a last line with no line feed after it.
• pair --list only reads: it makes no folder and takes no lock unless there is a run-out code's line to take out, or a device's line from before lines said whose they are to bring up to date. Asked through the door it writes nothing at all.
• A line names this installation by its folder. Move the folder and its devices' lines still name the old one: sshd finds no script there, the apps are refused, and neither pair --list nor doctor sees the lines any more, because they are no longer this installation's. Take them out of authorized_keys by hand (they end blog.sh:<device>) and pair the devices again from the new place.

The ten minutes are kept by the engine: the code's key can do nothing but ask it, and it refuses a key that arrives late. The code's line also carries sshd's own expiry-time as a second lock; that one is coarse (sshd reads it to the minute, and in summer time an hour late), so a line nobody came for may sit in the file that much longer before sshd itself refuses it. The next ./blog.sh pair, of any kind, removes it, and doctor mentions one that is left.

It needs the blog and the SSH server in the same account: a plain server, or a Mac with Remote Login turned on. pair checks that SSH answers before it makes a code, and asks for the one thing it cannot know -- the address this machine has from where the phone is. What it offers is the machine's number on its network, which a phone on the same network can always use; a name works where the phone can look it up (--host and --port say it without being asked; --no-wait prints the code and leaves). Where the blog lives in a container the keys are the host's and pair cannot reach them; that setup is written by hand, as above. BLOG_SH_AUTHORIZED_KEYS names the file for an account whose sshd reads another one. Write it into env.sh: pair and doctor both read it there, so the list of devices and the diagnosis are about the file the code was written into. Said only in a terminal it is gone with the terminal, and the next pair --list looks into the account's default file and finds nobody. What sshd itself is set to read the engine cannot see; that the two agree is yours to check (sshd -T | grep -i authorizedkeysfile, as root).

For whoever writes an app: the code is a link, blogsh://pair?v=1&h=<host>&p=<port>&u=<user>&k=<key>&f=<prints>&n=<site>, its values written as a web form writes them -- a space in the site's name is a +, and a + would be %2B. k is the 32 bytes of an ed25519 private key in URL-safe base64 with no padding; f is the SHA-256 fingerprints of the server's host keys in the same alphabet, joined by dots, and may be absent. Connect with that key, refuse a server whose key is not among the fingerprints, ask for the command enroll and write one line of JSON, {"key": "ssh-ed25519 AAAA...", "name": "the device's name"}. The answer is one object: {"ok": true, "device": "..."}, or ok: false with error one of expired, used, unknown_code, bad_key, bad_request -- and, when it is the machine rather than the code that is at fault, engine_failed (with the engine's words in message), no_ruby, no_cd or unknown_command. key_in_use is a key that already stands on another line of the account's file -- another blog's, or one written by hand: sshd runs the first line a key is on and never a second, so an app makes one key for each blog it connects to. From then on the app's own key works as any app's does.

A device let in this way can show the others and take itself out. Both are run requests like any other:

{"args": ["pair", "--list"]}
{"ok": true,
 "devices": [{"name": "Daniel's iPhone", "fingerprint": "SHA256:k/JB...QCo", "self": true},
             {"name": "Tablet",          "fingerprint": "SHA256:wL8H...u+w", "self": false}],
 "self": "SHA256:k/JB...QCo"}

{"args": ["pair", "--revoke"]}
{"ok": true,
 "revoked": {"name": "Daniel's iPhone", "fingerprint": "SHA256:k/JB...QCo"},
 "devices": [{"name": "Tablet", "fingerprint": "SHA256:wL8H...u+w", "self": false}],
 "self": null}

devices are in the order pair --list numbers them at the terminal, and a fingerprint is written as ssh-keygen -l writes it: SHA256: and 43 characters of base64 with no padding (an empty string for a line whose key somebody's hand has left unreadable). self -- on each device, and once beside the list -- says which of them is asking; it is null, and every device's is false, for a key whose line does not say whose it is: one written by hand, or one of a pairing older than the word, until ./blog.sh pair has been run at the terminal once -- and where the engine reads another key file than sshd does (BLOG_SH_AUTHORIZED_KEYS belongs in env.sh; one a session arrives with is not listened to). An app shows the list all the same and offers no way out.

--revoke takes out the device that is asking and no other; nothing may follow it. The request is answered -- sshd does not end a session because the key's line has gone -- and the next connection with that key is refused by sshd itself, so an app forgets the blog when it reads ok: true. (Every line of this blog that holds the key goes, should there be more than one. A line that is not this blog's -- one written by hand, another blog's -- stays, and a key that stands on one still opens what that line opens.) The refusals: device_unknown when the blog cannot tell who is asking (self was null), busy when somebody else is changing the file at that moment (nothing was taken out; ask again), write_failed and read_failed when the file could not be written or read, keys_path when BLOG_SH_AUTHORIZED_KEYS names a path that cannot be expanded, and bad_args for anything else after pair -- a code, an address, a name. Taking out ANOTHER device is done at the terminal, by whoever can sit at it: ./blog.sh pair --revoke. A blog whose app was set up by hand answers --list with no devices, since none came in by a code.

Only the front page. Type and tag listings, the RSS feed, the sitemap and the search index stay strictly chronological -- a pin is a statement about the front page, not about the archive. Toggling it is a small deploy, because pagination is anchored and the front page is the only flexible one. Pin a second post and the newest of them wins, with a warning in the build output.

publishing:
  slots:
    - "mon 09:30"
    - "wed 09:30"
    - "fri 09:30"
    # or a single "daily 09:00"

The draft dialog then names the next FREE slot in the [s] choice itself, and the prompt offers it: Enter accepts, typing a date overrides it, the cancel word backs out. Free means no other scheduled post is aimed at that exact time, so three drafts written in one evening queue onto three consecutive slots instead of publishing together, and the confirmation says which post goes out before this one.

The offer also names the earlier slots it had to walk past and the post sitting in each, so a queue that seems to skip a day explains itself. The properties dialog of a scheduled draft prints the whole queue for the same reason, with an arrow on the post you are looking at.

Slots only ever suggest. A post scheduled by hand for 14:17 occupies no slot and blocks nobody, nothing moves a post that already has a time, and without the key in config/site.yml the prompt is the plain one it always was. Times follow site.timezone, daylight saving included -- "mon 09:30" is 09:30 on the wall clock on both sides of the change. The publish-scheduled cron still runs on its interval, so a slot publishes within one tick of its time.

Working the queue

./blog.sh queue (also a wizard menu entry) shows every scheduled post in publish order and acts on the one you pick:

• [u] / [d] move it a slot earlier or later. Moving exchanges times with the neighbouring post -- the set of occupied times never changes, only which post sits in which. A hand-scheduled 14:17 stays a 14:17. The cursor follows the post you moved, so pressing [u] again carries the same post further.
• [m] picks the post up and carries it: the arrows then move the post itself through the queue, Enter puts it down and Escape leaves the queue as it was. Carrying from the eighth slot to the second steps the six in between back one slot each, so the same times stay occupied and the whole move is one write instead of one per slot. For a single slot [u]/[d] are quicker; [m] is for the longer trip, and it is offered in a terminal only -- a piped run has [u]/[d] and no screen to carry anything across.
• [p] publishes it right now, the same flow as publishing a draft by hand (announcement included).
• [s] asks for a different time, same prompt as scheduling.
• [n] returns it to the drafts; the post keeps its text, loses only the plan.

When a post leaves the queue -- published now, or removed -- its time is free again, and the screen offers to let the posts behind it each step forward into the gap, every one taking over its predecessor's time. It only offers: a hand-picked date further down may be deliberate, and nothing moves a post's time except you. A post whose time already passed is waiting for the cron and can't be reordered.

If the publishing cron happens to be running at the moment you move something, the move is refused rather than written: the two would be writing the same files, and the cron holds them for a few seconds at a time. Press the key again in a moment.

The preview rebuilds once, when you leave the screen, not after every move.

./blog.sh queue --json prints the queue as data instead -- one row per scheduled post in publish order, with its position, time, slug, year, title and whether its time has already passed -- and acts on nothing. Beside the rows it says when something last ran the queue (scheduler.last_run), or null where nothing ever has: on such a blog a post past its time is nobody's to wait for, and both the screen and the refusal say so and point at ./blog.sh publish <slug>.

Whitelisted: .pdf .zip .tgz .epub .txt .md .ics .gpx .csv (.tar.gz is not, because only the last suffix survives the rename -- use .tgz). A post whose text is a short line plus attachments is filed under DOCUMENTS, which appears in the nav once the first such post exists; a longer article that attaches its data stays an article with a file on it.

Every source also runs without the wizard, for cron or a scripted migration -- one scripts/migrate_<source>.rb each, e.g. scripts/migrate_bluesky.rb <handle>, scripts/migrate_instagram.rb <export-dir>, scripts/migrate_wayback.rb <https://dead-blog.example>, scripts/migrate_feed.rb <export.xml | feed-url>. Those skip the preview and write immediately; see the README.

A wizard that wrote nothing says so with its exit code. Cancelling leaves with 1, and so does reaching the end of the input without an answer -- which is what a script, a cron line or a pipe does. Zero means the import ran; it never means "nobody answered, so nothing happened".

Two things to expect on a real archive:

• It is slow, and it says so. Media is downloaded per post, so a few thousand posts run for hours. Every phase reports progress -- what it's reading, how many items it found, then a 12/847 counter -- so a quiet terminal means something is wrong, not that it's working. Sample before committing to that: every script takes LIMIT=20 to import only the first twenty, which is enough to see whether the mapping does what you expect. A second full run then overwrites them in place.
• The deploy guard will stop you afterwards, because a bulk import is exactly the "file count swung wildly" shape it watches for. That's working as intended: check the numbers, then re-run with --force.
• The summary names what HTML could not become blocks. Every adapter that parses HTML bodies counts the elements it had to drop -- embeds and forms, usually -- and the summary lists them by name and count, so a silent summary means nothing was lost, not that nobody counted.

Per-source walkthroughs -- where to get each export, what is kept and skipped, undo, troubleshooting -- live in Importing.

Re-running an import is safe -- posts are matched on their source identity and overwritten in place, never duplicated (Importing); the same identity is the safe selector when undoing an import.

Back up content.nosync/ before the first real import (tar czf ../content-backup-$(date +%F).tar.gz content.nosync) -- it isn't in git, and on a server there's nothing else to fall back on.

Writes the archive as a tree of markdown files with YAML front matter, in Jekyll's layout: _posts/2026-05-01-slug.md, _drafts/slug.md, pages at the root, media copied under assets/<year>/<slug>/. Without a directory it writes to tmp/export. A directory that already has something in it is refused until you repeat the command with --force, which writes alongside what is there -- an export never deletes anything, at either end. With --force, files an earlier export of this site wrote are refreshed in place; anything else -- a cloned site's own _config.yml, a post of somebody else's under the same file name, a different picture under the same path -- is left exactly as it is, the post of ours goes beside it under another name, and the summary lists what was left alone.

A post that cannot be written -- a stray byte from an old import, a slug that is not one path segment -- is named at the end and the rest of the archive still comes out; the command then exits 1, so a backup made by cron is seen to be short.

It reads only the archive on disk -- deliberately, so it works on an installation whose env.sh is gone or whose config no longer parses.

Three things are worth knowing before you rely on the result:

• The summary counts what could not stay markdown. Video, audio and link cards are written as HTML -- video and audio deliberately, because the engine's own !![caption](url) reads as an exclamation mark and an image to everybody else's markdown parser. Every engine that passes HTML through renders them properly, and importing the tree back gives them again as blocks -- each carries its own definition in a comment above it and a closing <!-- /blogsh:block --> line under it, both of which other engines ignore. (Trees exported before 1.8 have no closing line and are still read; an embed with a blank line inside it came home from those with part of its markup as text.) It also says how many of the media files copied no block names: they are in the tree, but an import back brings home only what the posts refer to.
• redirect_from is written in the shape jekyll-redirect-from reads, and it merges both kinds of old address -- where the post lived on the platform it came from, and where it lived here before a rename. On a Jekyll site with that plugin, every address the post has ever had goes on answering.
• An export can be imported back, into an EMPTY archive. ./import.sh → Markdown tree reads the blogsh: block the export writes, so posts keep their series, their redirects, their announcement URLs and their other languages -- a post's translations ride under blogsh: whole, with the address and the old addresses each language has, since no other engine has a word for them, and with each file their blocks show named by the path it has in the tree, so the import brings it and gives both texts the one name it has afterwards (the body of the file is the post's own language; what the site says about itself in the other ones is config/site.<lang>.yml, which is configuration and travels with the backup, not with the export). That is the supported way to move an installation to another machine or another host, and -- run against a scratch copy -- the way to check that an export really did come out whole.

⚠️ Not into an archive that already holds those posts. A post that carries an identity of its own -- imported from Twitter, Ghost, a feed -- is matched by it and updated in place. Everything you typed yourself carries {platform: manual} and nothing else, and the engine refuses to match two of those on purpose: pairing them would overwrite one person's writing with another's. So each hand-written post is written AGAIN under a serial slug. Every other rule in check lets the copy pass, because it has an address of its own; only its "looks like a copy of another" finding catches it, and only after the fact. On a blog whose posts are all hand-written that is the whole archive, twice. The wizard recognises this site's own export by its posts -- the blogsh: key every exported post carries, and slugs this archive already has -- which works for exports made by any version, and says so before it asks for confirmation. A tree of ours going into an archive that already holds posts is also asked about outright, with no as the default. But the rule is simpler than the warning: the target should be empty.

/archive/ is a map of the site in two levels. The first is a row per year with a strip of twelve months, each month shaded by how much was written in it; the second, /archive/<year>/, is one line per post, grouped by month, oldest first. No excerpts and no pictures: this is an index, and its whole point is that twenty years fit on one screen. Pagination cannot do that -- it is anchored to the oldest post, so /page/128/ says nothing about whether it holds 2009 or 2014. Every post's date badge links into the month it belongs to, so a reader who finds one post can see what surrounded it.

Under the map a legend says what the shading means -- the four steps between "less" and "more", in the map's own colours. A year's page opens with that year's row of the map again, behind the words "jump to a month": a month with posts is a link to its section further down the page, shaded as it is on the map.

A year nobody wrote in gets a row on the map and no page of its own: an empty page is an invitation to a dead end. A post is filed under the year of its ADDRESS, so /archive/2025/ and /posts/2025/ always agree.

/tag/ is every tag the site has, as pills, with a superscript count of how often each was used. It is built alphabetically -- folded, so an accented name sorts where a reader expects rather than after z -- and a reader can switch it to by-count, which is remembered for next time. Only tags that have a page of their own appear, so the list never points at an address the build did not write. Above the list a row of letters -- the ones that have tags under them -- jumps to each letter's band; by-count order has no bands, so the row is put away while that order is shown.

/series/ is every series the site has, a line each: the name, how many parts, and the years they span. The one still being written comes first -- the order is by the newest part. A series is listed once it has a page of its own, which is once it has two published parts, and the name in a series' own heading leads back here, as a tag's leads to /tag/. A site with no series has no such page.

None of the three needs a menu item to work, but nav: in site.yml is where you would put one; see Configuration in the README.

A picture post's card carries the picture. A card in a listing is cut by height, and it keeps its first block whatever that weighs -- so a photograph under one line of words used to be left off the card of a post that is that photograph. For a post whose kind is image or video (the icon in its date badge says which) the medium now goes first and the cut runs over what follows. A medium taller than it is wide is held to a height rather than given a screen to itself. An article with a photograph in it is still an article, and its card is cut as it always was.

tag_icons:
  - tag: "fotografie"
    icon: "image"
  - tag: "kolo"
    icon_svg: '<svg viewBox="0 0 24 24" ...>...</svg>'

A tag is matched here by its address -- the /tag/<name>/ its listing lives at -- so how the name is spelled, here or in a post, makes no difference: sci-fi, Sci Fi and sci_fi are one tag, share one page and wear one icon. A tag that leaves nothing to be addressed by, an emoji or a piece of punctuation, has no page and takes no icon either.

The order is the priority. Most posts carry more than one tag -- 68% of them on the archive this engine was built around -- and the tag a post was given FIRST is usually the one an importer added, not a subject: twitter opens 1256 posts there. So the first entry in this list that a post has is the one it wears, and the site owner decides once instead of post by post.

icon names one the engine ships. Eight of them are the content types themselves -- text, quote, chat, image, video, audio, link, document -- and the rest are the things blogs are about:

They are line drawings on the same grid as the eight, so a badge wearing one looks like a badge. doctor prints the whole list when a name is not among them, which is usually a synonym away -- bicycle for bike. A footer link in social: can wear one too, where the network marks have nothing to offer: icon: globe for somebody's other site.

icon_svg is your own drawing, on the same 24-unit grid (viewBox="0 0 24 24") and stroked in currentColor so it follows the light and dark themes. It does not have to be drawn from scratch: open an icon from any set that works on that grid -- Lucide, Feather and Tabler all do -- copy the <path> elements out of its file and paste them between <svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="2"> and </svg>. Mind the licence of whatever you take, and if the set fills its shapes rather than stroking them, drop the fill="none" and take stroke out. Scripts, styles and event handlers are stripped out of it before it reaches a page -- the same treatment an imported embed gets, and for the same reason. doctor says when an icon name is one the engine does not have, when an icon_svg holds no <svg>, and when it is drawn to another scale. 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, and the tag falls back to what it would have had with no entry here.

A tag with no entry here changes nothing: its listing keeps the generic tag icon and its posts keep the icon of their content type.

./blog.sh empty trash       # deletes every trashed post for good
./blog.sh empty versions    # keeps each post's newest version, removes the older ones

Both say how much they are about to delete and confirm by having you type that number -- the way delete has you type the slug. A trash has no slug to repeat back, and the count is the one number you have just been shown, so typing it means having read it. Anything else, including an empty answer, cancels and deletes nothing.

empty trash takes the media of a trashed post with it, and covers both shapes the trash has had: today's trash/<year>/<slug>/ and the flat trash/<slug>/ of an installation older than that.

empty versions deliberately keeps ONE version per post -- the newest. Versions exist to answer "give me back what I just overwrote", and that answer is the newest one; removing it too would take away the thing they are for.

doctor mentions a trash that has anything in it, with its size. Not as a fault -- a trash with posts in it is a trash doing its job -- but because nothing else on the site ever says it is there.

Both answer as data when asked: doctor --json and check --json print one object each, every finding in it, for a program rather than a reader -- and check --languages --json prints the table of languages the same way.

doctor asks whether the installation is sound and takes a second; this asks whether the archive is, and walks all of it -- two commands so the fast half keeps being run, and it is the fast half that belongs before a deploy. check reads the content on disk, so it works before a build has ever run, and it names a post and a slug for every finding rather than a file under public.nosync: something to go and fix.

The one thing it looks at outside the archive is config/site.yml, and for the same reason: this is the command people run before a build, and a config the build will refuse is not something to find out afterwards. It reports that file in doctor's words, so the two never describe it differently.

What it looks for, each with a line saying what to do about it:

• A config/site.yml that is missing, empty, will not parse, or cannot be opened. The build stops on all four and doctor explains all four; check used to read the config only to pick the language it printed in and say nothing about it, so an edited config could be answered with "the archive is sound" and an exit code of 0. The parse error carries the line and column Psych knew about.
• A post file that will not read, a date nothing can parse, a post whose text is not a list of blocks, a slug or a draft token that is not one path segment (a slash or a .. in it), tags that are not a list, a block whose pictures, poster, list items or formatting are not a list, or a type: the engine does not know. The build refuses to run on all but the last, or writes the page nowhere good, so check says so first: without this it counted the archive minus the broken file and called the rest sound. The unknown type is stored on the post and read by nobody -- no listing, no menu entry, no icon -- and the fix line points at the tag route, which is usually what somebody reaching for a ninth type wanted: a tag named in nav: has a listing, pagination, a menu entry and a feed.
• A post file the build never reads. Posts are read from exactly content.nosync/posts/<folder>/<post>.json; one lying directly in posts/ or a level deeper -- an rsync with the wrong trailing slash, an export unpacked one folder too far in -- is in the archive and on no page, and neither the build nor check used to say so. A warning, with the path. Hidden files are left alone.
• A file a queue move stepped aside and a crash left parked. The parking name is dotted precisely so no listing shows it -- which also means nothing would ever find one again without this. What to do with it depends on whether the post inside is still in the archive somewhere: a copy of a post that landed is a leftover to compare and delete, a parked file that is the only copy of its post is one to put back under a free name, and the finding says which of the two it is looking at. It never tells you to write over the post standing at that name.
• Media a post asks for and hasn't got -- a video's poster image included -- usually an import whose download failed. The page renders a hole. A file that is there and useless -- empty, unreadable, or a folder under the picture's name -- is reported the same way, with a sentence that says which it is; and a video whose index sits at the end of the file is noted, since it plays but makes every reader wait for the whole download before the first frame.
• Images stored as 1px or smaller. The build treats those as tracking pixels and drops them together with their caption, so the page loses both without saying so.
• Internal links pointing at nothing. Typically a permalink left over from an import, or a slug renamed back before renames left a redirect behind.
• Links written relative to the post rather than to the site -- ./?item=another-post, photo/index.php?gallery=3, ../about/. A dynamic site could afford those; a static one resolves them inside the post's own address, and a static host ignores a query string, so the link answers 200 with the page the reader is already on. Nothing breaks and nobody arrives, which is why these survive audits: rewrite them as rooted paths. A bare #fragment is left alone -- resolving against its own page is the point of it.
• Media directories no post owns -- left by a deleted or renamed post, or an import that ran twice. Nothing links to them; they cost disk, not correctness, which is why they are a warning. Names are compared the way macOS and iCloud compare them, ignoring letter case and unicode form, so a directory restored in another form is not called orphaned while the post is reading its pictures from it.
• Files in a post's own media directory that the post no longer names -- a source that dropped a picture leaves its file behind, because an import only ever adds. A warning too; dotfiles are left alone.
• Two series whose names differ by a character or two -- usually one series with a typo that quietly founded its own. A warning; names differing only in digits are left alone (rok-2025 next to rok-2026 is two year-series, not a typo).
• One old address claimed by two posts. Whichever renders last wins and the other's readers land on it.
• Two posts that would be served at one address. The build refuses to run at all in this state, so this is the one finding that stands between you and a site that cannot be rebuilt. Two addresses that differ only in letter case or in how an accent is encoded (Praha and praha) are reported as well, as a warning: on a Linux server they are two, on macOS and in iCloud they are one folder, and one of the posts is missing from the site.
• A post that looks like a copy of another -- x-2 beside x in the same year, with the same title, the same moment and the same content (text compared by its words, every other block -- a link, a quote, a list, a picture -- compared whole). That is what importing an export back into an archive that already held it leaves behind: every hand-written post a second time, each under its own address, so nothing else here would object. A warning, not an error, and deliberately narrow -- a slug that ends in a number beside the same slug without one is ordinary (an importer that keeps the source's post id in the slug makes exactly that), so all four have to agree before it says anything. Two link posts that open with the same line and point at different articles are not copies, and are not reported. Delete the numbered copy; the original keeps its address.
• A redirect_from the build will not serve -- one whose first segment belongs to the site itself (/tag/..., /posts/...), or whose shape no directory can be made of. The build says so once, in the middle of a log nobody keeps, and the old address quietly 404s; worse, a link pointing at it used to pass as sound. The same goes for an old address -- in redirect_from or former_slugs -- that a live post or page now stands at: the build serves the live one and skips the redirect in one line of its log, so every link to the old address reaches the wrong post.

• Text carrying HTML entities instead of the characters they stand for. journalists & writers reads as journalists & writers on the page: the build escapes it again, correctly, because as far as it knows the ampersand is what you wrote. Twitter escapes &, < and > in its archive without saying so, and the importer only learned to decode them in 1.4 -- so an archive imported before that carries them, and upgrading cannot help, since by then they are in the posts. Reported rather than corrected: somebody writing about html has every right to & in their text.
• Two posts asking for one address in one language -- a translation and another post that both claim /de/…, which the build would resolve by serving one of them and dropping the other. And a text filed under the site's OWN language in translations, which nothing reads: in that language the post is its own title and text.

• A config/site.<lang>.yml that nothing reads -- written for a language the site does not publish, carrying a key the engine does not know, or translating something site.yml does not have. All of them do nothing at all, and all of them look like the work is done. And one whose menu or footer links go to other places than site.yml's: a translation changes the words, not where they lead. A word for a tag no published post carries is worth a look rather than an error: it shows nowhere, and nothing is broken. Worth a look in the same way: a name for a series nobody writes, a menu item or a footer link with no word of its own (shown under the site's), a title given as nothing (the site's own stands), a fallback naming a language the site does not publish, and a language with a borrowed interface that does not say what it is called (language_name).

• A language named in site.locales that the engine has no locale file for. A typo there is not a typo in one language: the build stops on it in EVERY language of the site, its own included, because the menu that offers the other languages needs each one's name. A language the engine has no words for may borrow another's: ui_language: <code> at the top of that language's own file, config/site.<code>.yml.
• site.fallback or site.ui_language in config/site.yml. That is where a language's own settings were kept before 1.9 gave each language a file; the build refuses the old place by name, in every language. Each value goes to the top of its language's config/site.<code>.yml.

It only reports, unless you ask it not to. On its own -- and that is how cron runs it -- nothing here deletes a directory or rewrites a post: the value of the tool is that its output can be trusted, and a checker that also acts has to be trusted twice. --repair is where the asking happens, one finding at a time and never without a key press; it is described below, and it earns its trust the hard way -- it adds rather than rewrites where it can, it moves files to the trash rather than deleting them, and it keeps a version of a post before changing it. Twenty findings of each kind are listed and the rest counted, so one bad import can't bury everything else. It exits non-zero on errors only, never on warnings, so it can hang off cron and speak up only when something is actually broken.

--online additionally asks the web about every link that leaves the site. It takes minutes rather than a second, which is why it has to be asked for by name. What it reports is deliberately narrow: a host that no longer resolves, and a page answering 404 or 410. A timeout, a refused connection, a 5xx or a 403 is the web saying "not right now", and reporting those would turn one flaky evening into forty findings that are all fine tomorrow. Anything that looks dead is confirmed with a second request before it is believed, because some servers answer a HEAD with 404 and a GET with 200 for the same address. Verdicts are remembered in tmp/link-check.json for two weeks, so running it again next week only asks about the links it hasn't seen lately; deleting that file just means the next run asks about everything.

--repair walks the findings and offers, for each one, the single repair that finding allows -- nothing is applied without a key press. A dead link to an old address is repaired on the target post, by writing that address into its redirect_from: one added line, your own text untouched, and every link to the old address answered at once, including the ones from outside the site that no check can see. That holds for an address of the web a post came from. One the site makes itself -- under /posts/, or under the folder of a language -- is an address no redirect_from may answer at: check says so in its advice, no repair is offered, and what answers there is the post's own old address, former_slugs (the wrong year in a link to /posts/2025/a-post/ is fixed in the link). A link written relative to the post is rewritten to the address it means. A media directory or file no post references is moved to the trash the engine already uses -- trash/<year>/<slug>/media/ -- and ./blog.sh restore <slug> puts it back; the repair pass never deletes anything. A file whose name differs from the one on disk only in letter case or unicode form is not a leftover at all: the pass offers to write the name the directory actually uses into the post, and never touches the file. Text carrying HTML entities is decoded one post at a time, and the offer says how many places in that post change and shows the first -- it is one decision for the whole post, so a post with an imported & and a deliberate one is worth a look first. A post that changed after it was checked (edited in another window, or from the phone) is refused with a sentence rather than decoded on the strength of a scan it no longer matches.

Where the right answer is a matter of judgement -- two posts claiming one old address, an image the author has to look at, a link to something this archive never had, a slug two posts share across two years, or a target that is still a draft -- it says so and passes over. A second run proposes nothing, because the findings it repaired are gone -- except for text an import escaped more than once, which comes off one layer per decision; the run says so when a layer is left, and the next one offers it. Run ./blog.sh rebuild afterwards to put the changes on the site.

The screen shows at most twenty findings of a kind and totals the rest in a "...and N more" line, which is right for reading and useless for acting on: a script that wants to add redirect_from for every dead link cannot work from a summary. --json prints all of them instead, each with the kind it is (link_dead, media_stray, series_similar...) and the data it is about -- the post's slug, the address, the file. The exit code is the same in both modes: 0 when the archive is sound, 1 when something in it is not.

Reads the archive on disk -- no build, no network, no env.sh -- and comes back in seconds even on a large archive. What it says, and why each line is there:

• The archive: posts split into published, drafts, scheduled and pages. The four add up to the total; a page that is also a draft counts once, as a page.
• By year and What they are: where the archive is thickest, and what it is made of (the dominant content type per post, the same one the /type/ listings use).
• Words: total, mean and median. Both averages, deliberately -- an archive half made of imported tweets pulls the mean far above the middle, and only the pair says so.
• Tags, Media (files on disk, or what the posts ask for when the media directory is not here) and Where it came from -- the platforms the archive is actually made of, which is a different number from how many the importers support.

--json prints the same figures unlocalized and unrounded, so the numbers can go into a post, a cron job or a graph.

The same selection feeds a sidebar card, switched on by its name alone:

widgets:
  on_this_day:
    # heading: "On this day"    # optional -- the engine says it in every language

(or in ./style.sh, under the sidebar). The card reads the site's own archive, so there is no account to give and nothing to fetch. What it shows, and why each rule is there:

• Only the day itself. A post from an earlier year on today's date, in the site's time zone. A day with nothing from an earlier year hides the card, heading and all -- there is no "this week" fallback, which on a small archive showed one post seven days running. A post written on 29 February is remembered on the 28th in the years without the day.
• One row per year, five at most. Round anniversaries (5, 10, 15, 20 years...) always get a row. The rest are spread along the years with today counted as taken, so the older a year is, the stronger its claim -- "a year ago" appears when there is too little older to fill the card, not every day.
• A titled post stands for its year, the longest first; an untitled one only when the year has nothing titled that day. Titles decide inside a year and never between years: on an archive grown from several platforms they mark where a post came from, not how good it is.
• The day rotates. One window for every five posts the day has, three at most, dividing the day evenly by the clock (0-12-24, 0-8-16-24). Anniversaries stay; the other rows go first to years the day has not shown yet, and a year shown again brings its next post. Under the rows, the rest of the day folds away in a list.

Drafts, pages and unlisted posts never take part. The rule has no settings: it behaves the same on a hundred posts as on thirteen thousand, because what it depends on is how many years an archive spans and how many posts one year has on one day.

The card's file (on-this-day.json, in the root of every language's tree) is written by every build, and turned over after midnight by the sidebar cron below -- which is why a site with the card wants that cron even with no other widget. The cron chooses from a catalogue each build leaves beside the build cache (.on-this-day.<lang>.json), so it never needs to know what a translation is; a file from another day has no window for the page's clock and hides the card rather than show yesterday as today.

So the block is a list you write, and it holds three different kinds of thing:

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

Leave share: out and no block appears. The order here is the order they are drawn in.

bluesky, email, facebook, linkedin, threads and x are plain links: one address each, nothing to ask, no script. mastodon asks the reader once which instance they are on -- in a row that opens under the buttons, in the site's own type -- and remembers the answer in their browser. Not in a dialog from the browser: those look like something the page did not make, browsers throttle them, and a box demanding the name of a server is the shape people are taught not to trust. And no third-party redirector, which would put an outside service on every post page and in the way of every share. copy puts the address on the clipboard and says that it did. system hands it to the operating system's own share sheet, which on a phone is Signal and WhatsApp and Telegram and whatever else is installed, so one control covers what a row of them could not.

Three of them need the browser to co-operate, and none is drawn where it cannot work -- a control that opens nothing is worse than no control. mastodon stays hidden until its script has run, system unless the browser has a share sheet, and copy unless there is a clipboard to write to. That last one has a condition worth knowing about: browsers only give a page the clipboard over https, so on a site served over plain http:// the copy button is not drawn at all. If the whole block would be empty -- every target you named turned out to be one of these three, and none of them could run -- the block stays hidden too, rather than leaving a heading over nothing.

Pixelfed is not on the list. It has no share address to send anyone to -- the request for one was closed without it -- and a post there wants a photograph rather than a link.

What gets prefilled is the post's NAME and its address; the reader writes the part that is theirs. Nothing appears on a page, on a draft preview or on an unlisted post: there is nothing to pass on from a contact page, a draft has no address anybody else can open, and handing a reader a button that posts an unlisted post to Bluesky is the mistake the unlisted flag exists to prevent.

Since 1.6 the build writes down what it produced -- in .build_cache.json in the installation directory -- and the next build leaves alone the pages whose inputs have not moved. Nothing you do changes: ./blog.sh publish and ./blog.sh rebuild work exactly as before, only quicker. The summary at the end says how many pages were left alone, so you can see it working.

Measured on this project's own archive of 6,639 posts, on the server it lives on: a rebuild that changes nothing now costs a seventh of what it did, and an ordinary publish about two fifths. Backdating is the case it can do least about, and the measurement says so plainly -- a post dated into the early 2000s still costs four fifths of the old build. A post arriving in the middle of the archive shifts every listing page between the front page and where it lands, so those pages really did change and really do have to be built. Importing an archive, which is backdating several thousand times over, is a full build for the same reason.

The ratio is what travels; the seconds behind it are one machine's. These are our own measurements, on our own archive, on its own server. Yours will differ with your archive, your disk, and whatever else the machine is doing at the time.

The cache is an optimisation and never an authority. Anything it cannot vouch for is built the old way -- rendered, read back, compared. A page somebody deleted or damaged in public.nosync/ by hand comes back on the next build, because the record is checked against what is actually on disk, and public.nosync/ is still swept clean of anything the build does not produce on every build, cache or no cache. Editing a template, a locale or site.yml throws the whole cache away, since any of those can change every page; so does changing SITE_BASE_URL, and so does a change of timezone -- including the one that happens without you touching anything, when a system update rewrites the rules of the zone you publish in. A stylesheet is the exception worth knowing: pages link it rather than embed it, so editing one changes the stylesheet and nothing else -- the build skips every page it would have rebuilt and the deploy sends the one file. The palette in site.yml is not that case, since the stylesheet it generates and the theme colour in every page's head both come from it.

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

Reach for rebuild --full when you want the site rendered from scratch -- after restoring public.nosync/ from a backup, say, or when you suspect what is on disk is not what the archive says it should be. It costs one slow build, and it still leaves a usable record behind for the build after it. (ruby build/build_blog.rb --full does the building half alone, if you want the site rebuilt without being deployed.)

They are one file under two names now. Nothing about publishing changes, and neither does the archive's copy: deleting a picture from public.nosync/ -- by hand, or by the sweep, or by a deploy with --prune -- drops that name and leaves the archive's. What DOES follow the link is the mode: making the published picture readable makes the original readable too, which is the direction that was wanted, because a picture the web server cannot read was the bug this makes impossible.

It saves disk and it does not save backups. Measured against this project's own: 200 files under two names take 101 MB on the disk and 201 MB in the backup, because the backup copies file by file and stores each name in full. Back up media.nosync/ as you always did -- that is the archive's copy, and it is the one that matters.

./scripts/deploy-web.sh             # only new/changed files
./scripts/deploy-web.sh --dry-run   # print what would happen, touch nothing
./scripts/deploy-web.sh --prune     # also delete files the build no longer generates
./scripts/deploy-web.sh --force     # ignore the manifest, re-upload everything
./scripts/deploy-web.sh --only=A,B  # just the listed files

Things worth knowing:

• The safety guards. Four of them, all measuring this build against the last build a deploy accepted -- recorded in .deploy_baseline.json before the first byte goes out, so no upload failure can move it:

A drop almost always means a broken build; the byte version catches what counts cannot -- the same pages, each nearly empty. Growth in bytes is only a notice, because adding a video is authoring, not a malfunction; a single file too big to host is caught separately and by name (below). If a swing is genuinely intended (bulk import, mass deletion), rerun with --force. An empty build is always refused.

The absolute floors keep the percentages usable on a small site, where two posts published at once would otherwise read as an explosion.

A change of the site's languages is not a swing. Adding one grows the build by a whole tree (/en/, every listing, tag and feed in it) and removing one shrinks it by as much, so the deploy says the languages changed, leaves those trees out of the comparison and holds the rest of the site to the limits above -- a broken build on the same day still stops. The files of a language the site no longer publishes are deleted from the target by that deploy, without --prune.

A drop also measures against the manifest when that is larger, since every entry in it is a file that really did upload. Growth never does: the manifest legitimately lags the build after a failed upload or on a fresh target, and reading that lag as growth is exactly what used to disable these guards. - One file-size limit, everywhere. A single file over 100 MB is refused -- when the post is saved (so you can still shrink it) and again before a deploy sends it. The same limit applies to every backend so the site stays portable: the strictest supported target (git pages) refuses anything larger. --force does not lift it, since the target would refuse the file on every run. Files between 50 MB and 100 MB are named but allowed. A file already on the target from before this limit existed is reported, not refused. - --prune is the only destructive flag. Without it, files the build stopped generating stay live on the target (the deploy log counts these "orphans"). With the git backend every deploy is a snapshot and prunes implicitly -- the log says "(snapshot deploy)". - The previous run's outcome is reported, not acted on. A deploy that failed or was interrupted says so at the top of the next one, and after three unfinished runs in a row it says that too -- however high the count, since stopping after N attempts would be its own dead end. - Manifests are disposable. .deploy_manifest*.json (one per backend) records what the target already has. Deleting one is always safe -- the next deploy re-uploads everything once and rebuilds it. The guards are unaffected, because their reference lives elsewhere. - ...with one exception worth knowing. rsync, rclone and git diff the target themselves, so a lost manifest costs one full re-upload and nothing else. For sftp, Surfer and a local directory the engine never reads the far end, so the manifest is also the only record of what stands on it: a file you delete at home after the manifest went missing stays on the target, and no flag will find it again. This is why a deploy says out loud that the manifest was written for another target instead of quietly starting over -- and why the target's identity ignores the switches that cannot move a connection (-v, -q, the order they are written in), so reformatting a line in env.sh is not a new target.

• Switching backends starts from a fresh manifest on purpose; the first deploy to a new target uploads the whole site. The baseline is shared across backends -- it describes the build, which is the same wherever it goes -- so switching targets no longer leaves the guards with nothing to compare against.

Checking the guards by hand

--dry-run needs no target and writes nothing, which makes it the way to prove the guards still behave before trusting a release. Copy a build to a scratch directory, point DEPLOY_TARGET_DIR at a throwaway path with DEPLOY_BACKEND=local, and work through the cases that are easy to get wrong:

Two things make this easier to reason about: the failure state is anything that leaves last_run.outcome in .deploy_baseline.json set to something other than ok, and a run under --only must never change that file at all (that is how the sidebar cron stays out of the way).