On this page
Offline and PWA
Docs get read in places with no signal: a plant floor, a survey site, a basement, a plane. Docsary can install as a progressive web app so that pages a reader has already opened stay available with the network gone.
It is off by default and enabled per site.
Turning it on
curl -s -X PATCH "$DOCSARY_API/v1/sites/acme" \
-H "authorization: Bearer $DOCSARY_KEY" \
-H "content-type: application/json" \
-d '{"settings":{"pwa":true}}'
settings is replaced wholesale, not merged. The call above erases any other settings the site had — logo, colours, footer links. Read the current object first with GET /v1/sites/acme, add your key to it, and send the result back.
With pwa enabled, every page links a web app manifest and registers a small offline script at /sw.js. Browsers then offer to install the docs, and the installed app opens standalone, without browser chrome.
What the manifest contains
/manifest.webmanifest is generated from site settings:
| Field | Source |
|---|---|
name, short_name |
settings.name, falling back to the site's name |
start_url |
/ |
display |
standalone |
theme_color |
settings.colors.primary, falling back to the default blue |
background_color |
#ffffff |
icons |
settings.logo if set, declared at sizes: "any"; otherwise empty |
Set settings.logo to an SVG for a good install icon. A single raster image declared as any will be scaled by the platform to every size it needs, and small launcher icons are where that shows.
When pwa is off, /manifest.webmanifest returns 404.
What it stores, and when
The strategy is network-first with a cache fallback. Online readers always get current content; the cache exists only to answer a request the network cannot.
On each request it fetches from the network. A successful response is stored and returned. If the fetch fails, the stored copy is returned. If there is no stored copy, the failure surfaces normally.
It handles GET requests to your docs site only. Non-GET requests, other origins, and API paths are passed straight through, so API traffic is never cached or intercepted.
Only pages a reader has actually opened are available offline. There is no precaching and no site-wide download. Practically: a technician who reads a procedure over the office network has it in the field; a page nobody opened is not there.
Search does not work offline. Results are produced on the server, so a new query needs the network.
Publishing and the offline cache
Publishing retires everything readers have stored. The next time a reader opens the docs online, the stored copies from before the publish are dropped and replaced as pages are read again.
The effect is that stale offline content cannot outlive a publish. It also means offline coverage resets after each publish: pages must be visited again to be available offline again. That trade — correctness over coverage — is the right one for documentation, where a confidently served obsolete procedure is worse than no page at all.
The new version takes over immediately rather than waiting for open tabs to close, so a reader never has two versions of the docs in play.
Turning it off
Set pwa back to false:
curl -s -X PATCH "$DOCSARY_API/v1/sites/acme" \
-H "authorization: Bearer $DOCSARY_KEY" \
-H "content-type: application/json" \
-d '{"settings":{"pwa":false}}'
Removing the registration from new page loads is not enough on its own — a copy already installed in a reader's browser keeps running, and would otherwise keep serving your docs from a cache nobody is maintaining. So /sw.js does not disappear when the feature is disabled. It starts serving a self-destructing version instead, which clears every cache it holds, unregisters itself, and reloads any open tab onto the live site.
/sw.js is cached for 60 seconds in both states, so an installed reader picks up the self-destruct within about a minute of the change. Turning offline mode off is a clean uninstall, not an abandonment.
Not included
No push notifications, no background sync, no offline editing, no app store packaging. This is offline reading of pages already read, and nothing more.