Skip to content

Commit d6301fa

Browse files
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 <[email protected]> * Removed path.join for manifest path Co-authored-by: Jacky Zhao <[email protected]> * 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 <[email protected]> * Adding protocol to start_url too then * formatting... * Adding fallback page * Documenting offline plugin * formatting... * merge suggestion Co-authored-by: Jacky Zhao <[email protected]> * merge suggestion Co-authored-by: Jacky Zhao <[email protected]> * merge suggestion Co-authored-by: Jacky Zhao <[email protected]> * merge suggestion Co-authored-by: Jacky Zhao <[email protected]> * merge suggestion Co-authored-by: Jacky Zhao <[email protected]> * merge suggestion Co-authored-by: Jacky Zhao <[email protected]> * merge suggestion Co-authored-by: Jacky Zhao <[email protected]> * merge suggestion Co-authored-by: Jacky Zhao <[email protected]> * merge suggestion Co-authored-by: Jacky Zhao <[email protected]> * merge suggestion Co-authored-by: Jacky Zhao <[email protected]> * merge suggestion Co-authored-by: Jacky Zhao <[email protected]> * merge suggestion Co-authored-by: Jacky Zhao <[email protected]> * 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 <[email protected]>
1 parent 27a6087 commit d6301fa

File tree

13 files changed

+235
-6
lines changed

13 files changed

+235
-6
lines changed

docs/configuration.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,12 @@ const config: QuartzConfig = {
2121
This part of the configuration concerns anything that can affect the whole site. The following is a list breaking down all the things you can configure:
2222

2323
- `pageTitle`: title of the site. This is also used when generating the [[RSS Feed]] for your site.
24+
- `description`: description of the site. This will be used when someone installs your site as an App.
2425
- `enableSPA`: whether to enable [[SPA Routing]] on your site.
2526
- `enablePopovers`: whether to enable [[popover previews]] on your site.
2627
- `analytics`: what to use for analytics on your site. Values can be
2728
- `null`: don't use analytics;
29+
- `{ provider: "umami", websiteId: <your-umami-id> }`: easy, privacy-friendly, open source, GDPR Compliant analytics;
2830
- `{ provider: 'plausible' }`: use [Plausible](https://plausible.io/), a privacy-friendly alternative to Google Analytics; or
2931
- `{ provider: 'google', tagId: <your-google-tag> }`: use Google Analytics
3032
- `baseUrl`: this is used for sitemaps and RSS feeds that require an absolute URL to know where the canonical 'home' of your site lives. This is normally the deployed URL of your site (e.g. `quartz.jzhao.xyz` for this site). Do not include the protocol (i.e. `https://`) or any leading or trailing slashes.

docs/features/offline access.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: "Offline Access (PWA)"
3+
tags:
4+
- plugin/emitter
5+
---
6+
7+
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`
8+
9+
## Offline Capability
10+
11+
Whenever you visit a page it gets cached for offline use. Depending on the kind of content, the process for caching is diffent:
12+
13+
- **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.
14+
- **Static Resources** (Fonts, CSS Styling, JavaScript): Quartz uses cached resources by default and updates the cache over the network in the background.
15+
- **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
16+
17+
You can edit the fallback page by changing the `offline.md` file in the root of your `content` directory
18+
19+
## Progressive Web App (PWA)
20+
21+
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.
22+
23+
- **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
24+
- **name**, **short_name**: Uses the `pageTitle` configured in `quartz.config.ts`
25+
- **description**: Uses the `description` configured in `quartz.config.ts`
26+
- **background_color**, **theme_color**: Uses the `lightMode.light` color configured in `quartz.config.ts`.
27+
- **start_url**: Uses the `baseUrl` configured in `quartz.config.ts`
28+
29+
### Default values
30+
31+
- **display**: this is set to `minimal-ui`

docs/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ This will guide you through initializing your Quartz with content. Once you've d
3030
3131
## 🔧 Features
3232

33-
- [[Obsidian compatibility]], [[full-text search]], [[graph view]], note transclusion, [[wikilinks]], [[backlinks]], [[Latex]], [[syntax highlighting]], [[popover previews]], and [many more](./features) right out of the box
33+
- [[Obsidian compatibility]], [[full-text search]], [[graph view]], note transclusion, [[wikilinks]], [[backlinks]], [[Latex]], [[syntax highlighting]], [[popover previews]], [[offline access]] and [many more](./features) right out of the box
3434
- Hot-reload for both configuration and content
3535
- Simple JSX layouts and [[creating components|page components]]
3636
- [[SPA Routing|Ridiculously fast page loads]] and tiny bundle sizes

package-lock.json

Lines changed: 5 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@
9494
"@types/flexsearch": "^0.7.3",
9595
"@types/hast": "^2.3.4",
9696
"@types/js-yaml": "^4.0.5",
97-
"@types/node": "^20.1.2",
97+
"@types/node": "^20.6.2",
9898
"@types/pretty-time": "^1.1.2",
9999
"@types/source-map-support": "^0.5.6",
100100
"@types/workerpool": "^6.4.0",

quartz.config.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import * as Plugin from "./quartz/plugins"
44
const config: QuartzConfig = {
55
configuration: {
66
pageTitle: "🪴 Quartz 4.0",
7+
description: "Quartz Documentation Page and Demo",
78
enableSPA: true,
89
enablePopovers: true,
910
analytics: {

quartz/cfg.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ export type Analytics =
1919

2020
export interface GlobalConfiguration {
2121
pageTitle: string
22+
description: string
2223
/** Whether to enable single-page-app style rendering. this prevents flashes of unstyled content and improves smoothness of Quartz */
2324
enableSPA: boolean
2425
/** Whether to display Wikipedia-style popovers when hovering over links */

quartz/components/Head.tsx

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ export default (() => {
1414

1515
const iconPath = joinSegments(baseDir, "static/icon.png")
1616
const ogImagePath = `https://${cfg.baseUrl}/static/og-image.png`
17+
const manifest =
18+
cfg.baseUrl == undefined ? "/manifest.json" : `https://${cfg.baseUrl}/manifest.json`
1719

1820
return (
1921
<head>
@@ -25,7 +27,9 @@ export default (() => {
2527
{cfg.baseUrl && <meta property="og:image" content={ogImagePath} />}
2628
<meta property="og:width" content="1200" />
2729
<meta property="og:height" content="675" />
30+
<meta name="theme-color" content="#faf8f8" />
2831
<link rel="icon" href={iconPath} />
32+
<link rel="manifest" href={manifest} />
2933
<meta name="description" content={description} />
3034
<meta name="generator" content="Quartz" />
3135
<link rel="preconnect" href="https://fonts.googleapis.com" />
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
import { QuartzComponentConstructor } from "../types"
2+
3+
function OfflineFallbackPage() {
4+
return (
5+
<article class="popover-hint">
6+
<h1>Offline</h1>
7+
<p>This page isn't offline available yet.</p>
8+
</article>
9+
)
10+
}
11+
12+
export default (() => OfflineFallbackPage) satisfies QuartzComponentConstructor

quartz/plugins/emitters/componentResources.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,11 @@ function addGlobalPageResources(
116116
document.dispatchEvent(event)`)
117117
}
118118

119+
componentResources.afterDOMLoaded.push(`
120+
if ('serviceWorker' in navigator) {
121+
navigator.serviceWorker.register('/sw.js');
122+
}`)
123+
119124
let wsUrl = `ws://localhost:${ctx.argv.wsPort}`
120125

121126
if (ctx.argv.remoteDevHost) {

0 commit comments

Comments
 (0)