How publishing works

Publishing docs — all chapters

What gets built

Your site is plain files. There is no database and nothing that needs patching. It is worth knowing the shape, because it is yours to move anywhere.

Path	What it is
`index.html`	The home page: your newest posts, or a page you chose. Further pages of posts are in `page/`.
`posts/`	One page for each published post, named by its slug.
`pages/`	One for each published page.
`categories/` · `tags/`	An archive page for each category and tag that has posts, and its feed if you publish those.
`media/`	Every photo, video and audio file, already prepared for the web, with a poster for each video and, if the setting is on, smaller copies of the larger photos.
`style.css`	Your theme. One file, with nothing fetched from anywhere else.
`feed.xml` · `feed.json`	RSS and JSON Feed, with whole posts.
`sitemap.xml` · `robots.txt`	For search engines.
`404.html`	“Page not found”, in your theme and language.
`favicon.ico` · `apple-touch-icon.png`	Your site’s icon, when the site has an avatar or the monogram setting is on.

Some files exist only when you have asked for what they do.

Path	When
`archive.html`	The archive is in your menu.
`subscribe.html`	The Subscribe page is in your menu.
`search.html` · `search.js` · `search.json`	Search is in your menu.
`podcast.xml` and its cover	You publish a podcast feed.
`blog.html`	A page is your home page, so your posts live here.
`cards/`	Share cards, for posts with no photo.
`drafts/`	Drafts you are sharing before they are published.
`_redirects`	On Netlify and Cloudflare Pages, when posts have old addresses.
`.well-known/atproto-did`	You use your domain as your Bluesky handle.

Feeds, the sitemap, robots.txt and link previews need Site URL to be set. Drafts are never built, unless you are sharing one.

Only what changed is sent

Selfish builds the same files from the same site every time, byte for byte. A page changes only when something on it changed. That is what makes it possible to send just the difference.

How it finds the difference depends on where the site lives.

Route	How it knows what is live
SFTP, WebDAV, S3, a folder	Selfish keeps a record, `.selfish-manifest.json`, next to your site. It lists each file Selfish put there and which post it belongs to. Every device you publish from reads the same record.
Netlify, Cloudflare Pages, GitHub Pages	The host compares for itself and stores only files that differ. Each publish replaces the whole site. The review compares with this device’s last publish.

The first publish to a place uploads everything, to create the record. After that a quick edit on a photo-heavy site sends one page, not every photo.

What is removed, and what never is

When you unpublish or delete a post, it comes off your live site at the next publish: its page, its photos, and anything made for it.

The rules Selfish follows are strict, and they err towards leaving things alone.

It removes only what it recorded uploading. A file that isn’t in its record is never removed. A file of your own that shares a name with one of the site’s files would be overwritten, apart from the four below.
On SFTP, WebDAV, S3 and folders, it never takes down what might just not have synced. If your live site has a post this device doesn’t know, it stays online unless you choose to take it down. On Netlify, Cloudflare Pages and GitHub Pages every publish replaces the whole site, so such a post would come down. The review says so, and the answer is to let iCloud catch up first.
The record is written last. If a publish is interrupted, the old record stands, and the next publish redoes the work.
A file that can’t be removed doesn’t fail the publish. Selfish tells you, and tries again next time.
Folders that a removal leaves empty are tidied away.

Your own files are safe

People often put their own robots.txt, favicon, touch icon or 404.html on a server. On SFTP, WebDAV, S3 and folders, if one of those is already there and Selfish didn’t put it there, Selfish leaves it exactly as it is and says so in the review.

Publishing from two devices

On SFTP, WebDAV, S3 and folders the record of what is live sits beside the site, so a second device knows what the first one published. If your live site has posts this device hasn’t synced yet, or newer versions of them, the publish screen says so before anything is replaced.

On Netlify, Cloudflare Pages and GitHub Pages the review can only compare with this device’s own last publish, and a deploy replaces the whole site, so let iCloud catch up before publishing from a second device. See Review the changes.

Old addresses

A post can remember addresses it used to have. Importers fill them in, and moving a post to another site leaves one behind. Selfish makes each old address lead to the post.

Route	How
Netlify, Cloudflare Pages	A line in `_redirects`: a proper, permanent redirect.
Everywhere else	A small page at the old address that sends the reader on at once and asks search engines not to list it.

The forwarding page belongs to its post, so it comes down if the post does.

Addresses without .html

By default a post is published at /posts/my-post.html. Site Settings → Site → Post Pages → Addresses without .html publishes it at /posts/my-post/ instead. It is off unless you turn it on.

Once you switch, in either direction, the addresses your posts had keep leading to them, in the way described under old addresses.
Feeds keep each post’s identity, so readers aren’t shown your old posts as new.
Amazon S3 shows these addresses only with static website hosting turned on for the bucket, or behind a CDN set to add index.html.
With a folder, whatever serves it has to show a folder’s index.html at the folder’s address. Most web servers do.

Check your host before switching a site that is already live.

Drafts, scheduled posts and unlisted posts

A post that is	Is it built?
A draft	No, unless you are sharing it. It syncs to your other devices through iCloud, but it is never published.
Published, with a later date	Not until that day. Then it goes out at the first publish.
Published but unlisted	Yes, at its own address. It is left out of your home page, archives, feeds, sitemap and search.
In Recently Deleted	No, and if it was live it comes down.

How long browsers keep things

On Amazon S3 and S3-compatible storage, Selfish tells browsers how long to keep each file: pages, feeds and the stylesheet are checked on every visit; photos and other media are kept for a week; icons for a day; and anything else, such as share cards and the search script, for an hour. On other routes your host decides.