Offline support

[zadeviggers]

Description

Work on adding opt-in, network-first (to keep content up-to-date), offline support to the docs site.

This is very much a WIP PR. There's still a lot of work to do before this is ready. I'm just creating this PR so that people have something to look at in the community call on Wednesday.

Big things still to do:

• Basic offline support
• Prioritise caching important assets, like CSS
• Generate a unique hash on each build to use to invalidate the cache
• Only cache pages in the user's selected language
• Prioritise downloading pages the user currently has open
• Fix long page loading time when offline.
• Indicate to the user whether a page was served from the offline cache or not
• More messaging to the user about the system status - installing, downloading content, removing, etc
• Make all strings in UI translatable
• Remove dependency on simple-vanilla-notifications?
• Clean up & comment code
• Fix translation not working in client-side scripts
• Move to external package

FAQ:

• Does it work in dev mode? No - the service worker needs to be able to get a list of generated routes to be able to cache stuff, and that can only happen at build time. This is good because the service worker won't interfere with the docs' development.
• Is it automatic? No - users have to opt-in to having offline capabilities by clicking a button. This is based on Fred's idea here.

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	69909e9
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/635874475c2b8600094ed56c
😎 Deploy Preview	https://deploy-preview-1888--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[delucis]

Hi @zadeviggers! Thanks so much for exploring this — it’s super cool and sorry we haven’t had time to really dive into reviewing this complex PR.

I’m wondering if you think we could use some existing packages out there to get some similar functionality? This is a lot of code we would need to maintain and debug in the future and it feels like maybe for some of it we could be re-using prior art from other packages.

[zadeviggers]

Using external package was actually the first thing I tried. I tried vite-plugin-pwa and several others, but they were all either too complex (e.g. they added a lot of extra pwa features that we don’t want rather than just offline mode, as well as being very hard to configure), or were just straight up incompatible with Astro for various reasons.
In the end, having a custom integration and service worker was the simplest solution.
It did make me realise that since this functionality is hard to get set up in an Astro project, maybe instead of having a custom implementation here, I could extract it all to a new npm package that the docs site could depend on?

[sarah11918]

Well @zadeviggers, sometimes these PRs just take time, and sometime they don't work out.

We've discussed this a few times now, and we keep coming back to the issue of not wanting to take on the maintenance burden of a PWA. Especially now that we have Astro docs on devdocs.io, we have an offline option for readers with the added advantage of being higher profile and putting us up with a ton of other docs.

So, we're closing this PR, BUT I do think a prominent link somewhere that these docs are available on devdocs.io would be a good idea for people who do want offline docs but don't know about it. Thank you for making sure this issue stayed on our minds, and the thought and attention you've given it. The final decision is that we're content to go with the devdocs.io solution for offline reading.