From 9c118804a948a74255d8df1dec8956ddff71e46f Mon Sep 17 00:00:00 2001 From: saberzero1 Date: Thu, 16 Apr 2026 16:38:31 +0200 Subject: [PATCH] docs: clarified setup guide --- docs/getting-started/installation.md | 9 +++++++++ docs/troubleshooting.md | 14 ++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index df927ec..bfbc10c 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -45,6 +45,15 @@ npx quartz sync --no-pull In future updates, you can simply run `npx quartz sync` every time you want to push updates to your repository. +> [!tip] First-time plugin install on a fresh clone +> The Quartz template ships with a `quartz.lock.json` that pins community plugins to specific commits. On a brand-new clone those pins may be older than the plugins' current dependency versions, which can cause a handful of plugins to fail to build on first install. If you hit build errors during initial setup, run: +> +> ```bash +> npx quartz plugin install --latest +> ``` +> +> This refreshes every plugin to the latest commit on its default branch and rewrites `quartz.lock.json`. See [[troubleshooting#Plugins fail to build on a fresh clone]] for details. + > [!hint] Flags and options > For full help options, you can run `npx quartz sync --help`. > diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 6c5ffd3..04db9d0 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -62,6 +62,20 @@ This means the plugin is referenced in `quartz.ts` but not installed. Either: - Install it: `npx quartz plugin add github:quartz-community/plugin-name` - Or remove the reference from `quartz.ts` +### Plugins fail to build on a fresh clone + +On a brand-new clone, `npx quartz plugin install` (or the plugin step run automatically by `npx quartz create`) may report a handful of plugins failing to build — typically around 10–15 of them. The git clone and checkout still succeed, but `npm run build` inside the plugin errors out. + +This happens because `quartz.lock.json` pins each plugin to a specific commit, and those older plugin commits may have been authored against earlier versions of `@quartz-community/types` / `@quartz-community/utils` whose published artifacts are no longer shipped in the dependency's git repo. The plugin's `tsup`/`tsc` build then cannot resolve the expected type declarations. + +Fix it by refreshing all plugins to the latest commit on their default branch: + +```bash +npx quartz plugin install --latest +``` + +This rewrites `quartz.lock.json` with the newest commits (which in turn pin newer `@quartz-community/*` versions whose built output is available), and rebuilds every plugin from scratch. After this step, subsequent `npx quartz plugin install` calls will restore cleanly from the refreshed lockfile. + ### `plugin install` hangs, OOMs, or fails on low-end hardware By default, `npx quartz plugin install` clones, fetches, and builds plugins in parallel across all your CPU cores. Each parallel worker may run its own `npm install` and `npm run build`, which is memory-intensive. On low-end laptops, Raspberry Pi, small VPS instances, or restrictive CI runners this can exhaust RAM, trigger the OOM killer, or make the system appear to hang.