Soapbox for Blygger

A blyg is a publication that follows the Blygger protocol: a set of documents at one address, describing every item you have published, each with a permanent id and a version history. Software that speaks the protocol can subscribe to it, recover its whole archive, and quote a specific version of a specific item. People using an ordinary feed reader can subscribe to its feed.

Partly, and it is worth understanding before you start.

• A post can be withdrawn. Trash it, make it private or password-protect it, and its content is no longer served. This does not depend on the plugin having noticed the change: before it serves anything, it checks that the post is still public, and withdraws it there and then if it is not. Its address keeps answering, with an empty document marked withdrawn. Readers that follow the protocol drop their copy. Copies already made by anyone else are beyond your reach, as with anything published on the web.
• A pin cannot be undone. A pinned version is served forever, even after the post is withdrawn. Pin deliberately.
• The address cannot be moved. Once the blyg has an item, its mount path and layout are fixed.
• Deactivating the plugin keeps all data and takes the blyg offline (its addresses answer 404) until you activate it again.
• Deleting the plugin also keeps all data, unless you tick "Delete all Soapbox for Blygger data when the plugin is deleted" in the settings. If you delete the data, every address the blyg ever served is broken for good, and reinstalling starts again with new ids.

Fixed paths (selected to begin with) serves the protocol's own file names under the mount: feed.xml, items/index.json, items/{id}.json. This is Blygger 0.3 as published, and every reader understands it. Many hosts cache addresses ending in .json and .xml aggressively, so check Site Health after you choose it; see the next question. Templated serves the manifest at /blyg/blyg.json and everything else through the WordPress REST API, at addresses the manifest names. It avoids the paths hosts cache, but it follows a construct the protocol has ruled on for version 0.4 and not yet published as part of 0.3 (the manifest locates the surface). A reader has to support that, and most do not yet: one that does not will find the manifest and then get 404s. Choose it only if you know your readers can use it. The choice is permanent once the blyg has an item, so it is made by you, on the settings screen, before publishing can be switched on.

Something in front of WordPress (your host's cache, Varnish, a CDN) is keeping copies of the blyg's documents for longer than the cache lifetime in the plugin's settings (five minutes unless you changed it). That matters: if you withdraw or edit a post, the old content keeps being served until the cache expires, which on some hosts is a month. Exclude the blyg from that cache. With the default settings that means the path /blyg/ and, in the templated layout, /wp-json/soapbox-blyg/.

• Managed hosts (Cloudways, Kinsta, WP Engine and similar): look for "Varnish exclusions" or "cache exclusions" in the application settings and add both paths. If there is no such setting, ask support to exclude them.
• Varnish: in vcl_recv, if (req.url ~ "^/(blyg/|wp-json/soapbox-blyg/)") { return (pass); }
• Cloudflare: add a Cache Rule for URI paths starting with /blyg/ and /wp-json/soapbox-blyg/, set to "Bypass cache".
• nginx fastcgi_cache or proxy_cache: if ($request_uri ~* "^/(blyg/|wp-json/soapbox-blyg/)") { set $skip_cache 1; }, with $skip_cache wired to fastcgi_cache_bypass and fastcgi_no_cache.

Many hosts add a caching instruction of their own to everything WordPress sends, often with a lifetime of a month. The plugin expects that: it states its own lifetime first, and a cache that is given the same instruction twice follows the first (RFC 9111, section 4.2.1). So an extra instruction after the plugin's is harmless, and Site Health does not warn about it. It warns when the first lifetime a cache would read is longer than the one in the plugin's settings. Either your server puts its instruction before the plugin's, or something on the site has removed the plugin's: a plugin or theme using the soapbox_blyg_cache_control filter must keep s-maxage in the value it returns. If it is the server, adding the path to a cache's exclusion list does not remove the header; ask your host's support to stop adding a Cache-Control header for /blyg/ and /wp-json/soapbox-blyg/ (with the default settings), then reload Site Health.

Yes, with Breeze's "Browser Cache" option on or off, and with no change to .htaccess. With that option on, the server adds a max-age chosen by content type to any response that has no Expires; and on a site where the option was switched on under Breeze 2.2.24 or earlier, every response also leaves with a thirty-day s-maxage appended, because the rule that older Breeze wrote is still in .htaccess. The plugin sends its own s-maxage first and its own Expires, so neither changes how long its documents are cached. Breeze's page cache does not store them either: the plugin marks each response with the DONOTCACHEPAGE constant, which Breeze and most page caches honour. Adding /blyg/ and /wp-json/soapbox-blyg/ to "Never cache these URLs" does no harm, and is not needed. If your site still has that older rule, saving Breeze's settings once makes Breeze rewrite its block without it. After installing or updating, purge Breeze and Varnish once, so that nothing cached earlier is left, and look at Site Health. Cloudways' Varnish keeps a document for as long as its own configuration says, whatever lifetime the response states. So whenever a document of the blyg changes, the plugin asks Breeze to purge its address from Varnish; see the next question.

When a post is published, edited, withdrawn or restored, or the blyg's settings change, the plugin works out which of the blyg's addresses changed (the manifest, the feed and the archive index; the item's own document, unless the item is new; the post's page, when an item is withdrawn or restored; and the mount, when the settings change) and tells the cache plugin beside it, once, at the end of the request:

• Breeze (Cloudways): Varnish is purged for those addresses. When a post is unpublished, Breeze is also given the address it was published at, so that Breeze drops the page from its own cache, from Varnish and from Cloudflare; by itself, Breeze 2.6.1 looks for a draft's page under its ?p= address and leaves the cached page in place. Two cases are purged from Varnish only, because Breeze does not clear its own page cache for them and offers no way to drop one address from it: a withdrawal that no save of the post causes (a post type switched off, a change made in the database), and a post unpublished by something that is not a signed-in user who may edit it, such as WP-CLI run without --user. That page stays until Breeze's own cache lifetime ends or its cache is purged. Cloudways' Varnish keeps what it caches for hours whatever lifetime a response states, so this is what makes a withdrawal prompt there. Without Breeze, add your mount path as a Varnish exclusion in the Cloudways panel.
• W3 Total Cache: each address is flushed from whichever of its caches are on, Varnish and a full-site CDN included.
• SiteGround Speed Optimizer: each address is purged from SiteGround's dynamic cache.

For as long as the cache lifetime under Settings > Soapbox for Blygger > Caching: five minutes unless you change it, and one minute, fifteen minutes or an hour if you do. When you withdraw or edit a post, your site answers with the new state at once; readers and caches that already hold a copy may keep using it until that time is up, and then ask again. A reader behind a cache can hold one copy after the other, so allow twice the lifetime before expecting everyone to have seen a withdrawal. Shorter means a withdrawal is seen sooner; longer means fewer requests reach your site. The same time applies to "not found": an address asked for just before its item is published can answer 404 for that long. Pinned versions are the exception. They never change, so they are cached for a year, and a pin cannot be withdrawn.

In the templated layout the documents are served through the REST API, and something on your site is restricting the REST API to logged-in users. The usual causes are a security plugin with a "disable REST API" or "require authentication for REST" setting, or a plugin whose only job is to disable the REST API. Allow anonymous access to the soapbox-blyg/v1 namespace in that plugin, or choose the fixed layout before you publish.

No. A blyg lives at an address of its own, which needs WordPress's rewrite rules. Choose any other permalink structure.

The protocol asks that an image address always serves the same picture once it has been published. If you need to change an image in a published post, upload the new one as a new file rather than replacing the old file in place.

When another blyg quotes one of your items, answers it or forks it, that site can tell yours, by sending a Webmention. It is off by default. If you switch it on (Settings > Soapbox for Blygger > Mentions), then for each mention your site receives it fetches the sender's page and its item document, and sometimes that blyg's manifest, to check that the document really refers to your item. See "External requests" below for exactly what that involves. Verified mentions are listed under Tools > Soapbox for Blygger, for administrators. Nothing is shown to visitors, and nothing from the other site is stored except its address, its item's id and its author's published name. If the Webmention plugin is active, it keeps the Webmention endpoint advertised on your pages, and this plugin advertises its own only in the blyg's manifest.

A version is made when anything the blyg publishes about the post changes: its text, its title, its address (so a change of slug is a version), its author's name, its featured image, or the HTML readers are shown even where the Markdown comes out the same. It can also be a change made by a plugin or theme update that alters how the post's content is rendered. Tools > Soapbox for Blygger > "Verify with render drift" lists posts that would publish a new version if saved now, so you can check after an update.

Test it before you publish anything, and above all before you run the backfill: what is published cannot be unpublished, only withdrawn. The plugin renders each post as a logged-out visitor would see it, by running the post through the_content outside the main loop. A plugin that hides content only inside the loop, or only on the post's own page, may not hide it there, and the full text would then be published in the blyg. Publish a test post, open its item document from the Blyg panel in the editor, and look at what it contains. If it shows more than a visitor should see, leave that post type unticked, or exclude posts with the soapbox_blyg_is_public filter.

Yes. Each site has its own blyg, its own settings and its own data. However the plugin is activated, publishing is off on a site until that site's administrator has chosen its address and layout and switched it on.