From 08c99940ba4869c10aea6a82f0fbd9917010d1a7 Mon Sep 17 00:00:00 2001 From: saberzero1 Date: Wed, 11 Mar 2026 19:43:12 +0100 Subject: [PATCH] docs: plugin development and setup guide --- docs/advanced/making plugins.md | 37 ++++++++++++++++++++++++++++++- docs/configuration.md | 14 ++++++++++++ docs/getting-started/migrating.md | 15 ++++++++++++- docs/getting-started/upgrading.md | 11 +++++++++ docs/hosting.md | 3 +++ 5 files changed, 78 insertions(+), 2 deletions(-) diff --git a/docs/advanced/making plugins.md b/docs/advanced/making plugins.md index 3b6242166..70616c0da 100644 --- a/docs/advanced/making plugins.md +++ b/docs/advanced/making plugins.md @@ -482,7 +482,7 @@ npx tsup npx quartz plugin add github:your-username/my-plugin ``` -Then add the plugin to your `quartz.config.yaml`: +This clones the plugin, builds it, and adds it to both `quartz.config.yaml` and `quartz.lock.json`. You can then configure it in your config: ```yaml title="quartz.config.yaml" plugins: @@ -498,6 +498,41 @@ import * as ExternalPlugin from "./.quartz/plugins" transformers: [ExternalPlugin.MyPlugin()] ``` +### Development Workflow + +During plugin development, you'll frequently install and uninstall your plugin to test changes. The following commands help manage this cycle: + +```shell +# Remove your plugin and clean up +npx quartz plugin remove my-plugin + +# Re-add after making changes +npx quartz plugin add github:your-username/my-plugin +``` + +If you've updated your `quartz.config.yaml` to reference a plugin that isn't installed yet, you can install it without manually running `add`: + +```shell +# Install all config-referenced plugins missing from the lockfile +npx quartz plugin resolve + +# Preview first without making changes +npx quartz plugin resolve --dry-run +``` + +To clean up plugins that are installed but no longer referenced in your config: + +```shell +# Remove orphaned plugins +npx quartz plugin prune + +# Preview first without making changes +npx quartz plugin prune --dry-run +``` + +> [!tip] +> Both `resolve` and `prune` fall back to `quartz.config.default.yaml` if no `quartz.config.yaml` is present. This is useful for CI environments where the default config is the source of truth. See [[cli/plugin#prune|prune]] and [[cli/plugin#resolve|resolve]] for full details. + ## Component Plugins For plugins that provide visual components (like Explorer, Graph, Search), see the [[creating components|creating component plugins]] guide. diff --git a/docs/configuration.md b/docs/configuration.md index 7fe01bc34..ae92c9009 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -143,6 +143,20 @@ npx quartz plugin add github:quartz-community/explorer This adds the plugin to `quartz.config.yaml` and installs it to `.quartz/plugins/`. +To install all plugins referenced in your config that aren't yet installed (useful when cloning a project or setting up CI): + +```shell +npx quartz plugin resolve +``` + +To remove installed plugins that are no longer in your config: + +```shell +npx quartz plugin prune +``` + +Both commands support `--dry-run` to preview changes. See [[cli/plugin|the plugin CLI reference]] for full details. + ### Usage You can customize the behaviour of Quartz by adding, removing and reordering plugins in `quartz.config.yaml`. Each plugin entry specifies its source, whether it's enabled, execution order, and any options: diff --git a/docs/getting-started/migrating.md b/docs/getting-started/migrating.md index 33a64b4ed..79edcd12e 100644 --- a/docs/getting-started/migrating.md +++ b/docs/getting-started/migrating.md @@ -267,7 +267,17 @@ Key changes: #### 4. Update CI/CD -Add `npx quartz plugin restore` to your build pipeline, before `npx quartz build`. See [[ci-cd]] for detailed examples. +Add `npx quartz plugin restore` to your build pipeline, before `npx quartz build`. This installs plugins from the lockfile at their pinned versions. + +If your CI uses `quartz.config.default.yaml` (or contributors may add plugins to config without updating the lockfile), also run `npx quartz plugin resolve` to install any config-referenced plugins that are missing from the lockfile: + +```shell +npx quartz plugin restore # install pinned plugins from lockfile +npx quartz plugin resolve # install any config-referenced plugins not yet in lockfile +npx quartz build +``` + +See [[hosting]] for detailed CI/CD examples and [[ci-cd]] for advanced configuration. #### 5. Commit and Deploy @@ -276,6 +286,9 @@ git add quartz.config.yaml quartz.lock.json git commit -m "chore: migrate to Quartz 5 plugin system" ``` +> [!tip] Cleaning up leftover plugins +> After migrating, you may have plugins installed from v4 that are no longer in your v5 config. Run `npx quartz plugin prune` to remove them. Use `--dry-run` first to preview what would be removed. + ### Plugin Reference Table Mapping v4 plugin names to v5 equivalents: diff --git a/docs/getting-started/upgrading.md b/docs/getting-started/upgrading.md index baa470331..d85e16f7e 100644 --- a/docs/getting-started/upgrading.md +++ b/docs/getting-started/upgrading.md @@ -27,3 +27,14 @@ npx quartz update ``` See the [[cli/update|CLI reference for update]] and [[cli/upgrade|CLI reference for upgrade]] for more details on available flags. + +### Cleaning Up Unused Plugins + +If you've removed plugins from your configuration during an upgrade, you can clean up the leftover files: + +```bash +npx quartz plugin prune --dry-run # preview what would be removed +npx quartz plugin prune # remove orphaned plugins +``` + +See the [[cli/plugin#prune|plugin prune reference]] for more details. diff --git a/docs/hosting.md b/docs/hosting.md index 644063515..a19dff714 100644 --- a/docs/hosting.md +++ b/docs/hosting.md @@ -12,6 +12,9 @@ However, if you'd like to publish your site to the world, you need a way to host > [!hint] > Some Quartz features (like [[RSS Feed]] and sitemap generation) require `baseUrl` to be configured properly in your [[configuration]] to work properly. Make sure you set this before deploying! +> [!tip] Keeping plugins in sync +> All hosting examples below use `npx quartz plugin restore` to install plugins from the lockfile. If contributors may add plugins to `quartz.config.yaml` without updating the lockfile, add `npx quartz plugin resolve` after `restore` in your build command to install any missing plugins. See [[cli/plugin#resolve|plugin resolve]] for details. + ## Cloudflare Pages 1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account.