docs: plugin development and setup guide

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.

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:

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:

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.

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.