Skip to content

Use a PWA Install Model for Offline Documentation Access

Status

Accepted — HybridOps docs use a web-app manifest plus service worker for installable offline access where the browser supports it. This is not a downloadable archive feature.

1. Context

HybridOps documentation is served as two branded static sites:

  • https://docs.hybridops.tech
  • https://learn-docs.hybridops.tech

Users asked for a way to keep documentation available with reduced network dependency, especially for:

  • travel and workshop scenarios
  • field reference use
  • Academy learners who want quick local access from a phone or laptop

The desired experience is lightweight and browser-native. It should not require:

  • separate packaging pipelines for zip exports
  • desktop installers
  • custom native applications

At the same time, browser behavior is inconsistent:

  • Chromium-based browsers can expose beforeinstallprompt
  • Safari generally does not expose the same install prompt flow
  • iPhone and iPad users typically rely on Add to Home Screen

The docs feature therefore needs a clear operational contract so product behavior and user expectations stay aligned.

2. Decision

HybridOps adopts a PWA-style install model for offline documentation access.

The documentation sites publish:

  • a valid web manifest
  • a registered service worker
  • install-oriented UI that appears when the browser exposes a supported install prompt

Behavior contract:

  • On browsers that support install prompting:
  • the site may show an Install offline docs action
  • installation uses the browser's standard PWA flow
  • On Safari and similar browsers:
  • users rely on the browser's native Add to Home Screen / save-to-device behavior
  • HybridOps does not require a custom prompt for that path

Scope boundaries:

  • This decision covers browser-based offline installability for the docs sites
  • It does not define a downloadable zip, PDF, or tarball export of the docs
  • It does not guarantee full offline fidelity for every future asset or dynamic feature

3. Rationale

3.1 Why a PWA-style model?

  • It is the lowest-complexity path to useful offline docs
  • It works across the public and Academy docs hosts with the same static build pattern
  • It fits the existing Cloudflare Pages deployment model
  • It avoids introducing another packaging and release surface just for docs archives

3.2 Why not promise a downloadable bundle?

  • A real downloadable offline bundle is a different product surface
  • It would require explicit packaging, versioning, integrity, and update behavior
  • It would create a second offline distribution contract to maintain

For the current HybridOps docs shape, that is unnecessary overhead.

3.3 Why explicitly mention Safari behavior?

  • Safari does not behave like Chromium for install prompting
  • Without documenting that, the feature looks broken rather than intentionally browser-native
  • The correct user expectation is:
  • supported browsers may expose an install prompt
  • Safari users can still pin the site with Add to Home Screen

4. Consequences

4.1 Positive consequences

  • Offline access stays simple and browser-native
  • Both public and Academy docs can share the same install approach
  • No separate archive build or download hosting is required
  • The feature remains compatible with low-cost static hosting

4.2 Negative consequences / risks

  • Install UX is browser-dependent
  • Safari behavior is less explicit than Chromium behavior
  • Some users may assume "offline docs" means a downloadable file rather than an installed web app
  • Service worker / manifest path regressions can silently disable installability

Mitigations:

  • Keep manifest and service-worker paths part of the docs publishing contract
  • Verify installability during docs build and deployment checks
  • Describe the browser behavior clearly in docs and UI copy

5. Alternatives considered

Alternative A — downloadable zip/tar offline bundle

Rejected for now because it adds packaging and release complexity that is not necessary for the current use case.

Alternative B — no offline capability at all

Rejected because it weakens practical usability for workshops, mobile use, and intermittent connectivity.

Alternative C — native wrapper app

Rejected because it is disproportionate to the current product need and introduces another runtime and distribution surface.

6. Implementation notes

The current implementation relies on:

  • manifest link in the MkDocs override:
  • docs/assets/overrides/main.html
  • service worker registration:
  • docs/assets/js/service-worker-register.js
  • install button logic:
  • docs/assets/js/install-app.js
  • cached asset behavior:
  • docs/service-worker.js

Publishing requirement:

  • the built docs site must publish the manifest at:
  • /assets/manifest/manifest.webmanifest

Operational note:

  • if the manifest path in the rendered HTML and the published site diverge, install prompting stops working even though the service worker may still load successfully

7. Operational impact and validation

Validation should include:

  • rendered docs HTML includes a manifest link
  • manifest URL returns 200
  • service worker URL returns 200
  • install action appears on supported browsers
  • Safari path is documented as Add to Home Screen, not as a broken missing prompt

The acceptance standard is:

  • Chromium-family browsers can install the docs as a web app when platform conditions allow
  • Safari users can still pin the site manually
  • the feature is described as offline installability, not as downloadable offline media

8. References

Maintainer: HybridOps License: MIT-0 for code, CC-BY-4.0 for documentation unless otherwise stated.

Runbooks

HOWTOs