zaine/quartz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: clarified setup guide

Browse Source
This commit is contained in:
saberzero1
2026-04-16 16:38:31 +02:00
parent 5bec6fb87b
commit 9c118804a9
2 changed files with 23 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/getting-started/installation.md
View File

@@ -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. 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 > [!hint] Flags and options
> For full help options, you can run `npx quartz sync --help`. > For full help options, you can run `npx quartz sync --help`.
> >

14
docs/troubleshooting.md
View File

@@ -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` - Install it: `npx quartz plugin add github:quartz-community/plugin-name`
- Or remove the reference from `quartz.ts` - 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 ### `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. 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.