feat: Making Quartz available offline by making it a PWA (#465)

* Adding PWA and chaching for offline aviability * renamed workbox config to fit Quartz' scheme * Documenting new configuration * Added missig umami documentation * Fixed formatting so the build passes, thank you prettier :) * specified caching strategies to improve performance * formatting... * fixing "404 manifest.json not found" on subdirectories by adding a / to manifestpath * turning it into a plugin * Removed Workbox-cli and updated @types/node * Added Serviceworkercode to offline.ts * formatting * Removing workbox from docs * applied suggestions * Removed path.join for sw path Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * Removed path.join for manifest path Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * Removing path module import * Added absolute path to manifests start_url and manifest "import" using baseUrl * Adding protocol to baseurl Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * Adding protocol to start_url too then * formatting... * Adding fallback page * Documenting offline plugin * formatting... * merge suggestion Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * merge suggestion Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * merge suggestion Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * merge suggestion Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * merge suggestion Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * merge suggestion Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * merge suggestion Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * merge suggestion Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * merge suggestion Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * merge suggestion Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * merge suggestion Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * merge suggestion Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com> * formatting... * Fixing manifest path, all these nits hiding the actual issues .-. * Offline fallback page through plugins, most things taken from 404 Plugin * adding Offline Plugin to config * formatting... * Turned offline off as default and removed offline.md --------- Co-authored-by: Jacky Zhao <j.zhao2k19@gmail.com>
2023-09-20 20:38:13 +02:00
parent 27a6087dd5
commit d6301fae90
13 changed files with 235 additions and 6 deletions
--- a/docs/features/offline
+++ b/docs/features/offline
@@ -0,0 +1,31 @@
+---
+title: "Offline Access (PWA)"
+tags:
+  - plugin/emitter
+---
+
+This plugin allows your website to be accessible offline and be installed as an app. You can use it by adding `Plugin.Offline(),` to the `emitters` in `quartz.config.ts`
+
+## Offline Capability
+
+Whenever you visit a page it gets cached for offline use. Depending on the kind of content, the process for caching is diffent:
+
+- **Pages** (HTML, your converted Markdown files): Quartz first tries to get them over the Network. If that fails, your browser attempts to fetch it from the cache.
+- **Static Resources** (Fonts, CSS Styling, JavaScript): Quartz uses cached resources by default and updates the cache over the network in the background.
+- **Images**: Images are saved once and then served from cache. Quartz uses a limited cache of 60 images and images remain in the cache for 30 days
+
+You can edit the fallback page by changing the `offline.md` file in the root of your `content` directory
+
+## Progressive Web App (PWA)
+
+Progressive Web Apps can have [many properties](https://developer.mozilla.org/en-US/docs/Web/Manifest). We're only going to mention the ones Quartz supports by default, however you can edit the offline plugins file to add more in case required.
+
+- **icons**: the `icon.svg` file in the `quartz/static` directory is used for all the icons. This makes it easier to scale the image since you don't need to provide an png for every size
+- **name**, **short_name**: Uses the `pageTitle` configured in `quartz.config.ts`
+- **description**: Uses the `description` configured in `quartz.config.ts`
+- **background_color**, **theme_color**: Uses the `lightMode.light` color configured in `quartz.config.ts`.
+- **start_url**: Uses the `baseUrl` configured in `quartz.config.ts`
+
+### Default values
+
+- **display**: this is set to `minimal-ui`