mirror of
https://github.com/jackyzha0/quartz.git
synced 2026-03-21 21:45:42 -05:00
193 lines
4.6 KiB
Markdown
193 lines
4.6 KiB
Markdown
---
|
|
title: quartz plugin
|
|
---
|
|
|
|
The `plugin` command is the heart of the Quartz v5 plugin management system. it allows you to install, configure, and update plugins directly from the command line.
|
|
|
|
All plugins are stored in the `.quartz/plugins/` directory, and their versions are tracked in `quartz.lock.json`.
|
|
|
|
## Subcommands
|
|
|
|
### list
|
|
|
|
List all currently installed plugins and their versions.
|
|
|
|
```shell
|
|
npx quartz plugin list
|
|
```
|
|
|
|
### add
|
|
|
|
Add a new plugin from a Git repository.
|
|
|
|
```shell
|
|
npx quartz plugin add github:username/repo
|
|
```
|
|
|
|
To install from a specific branch or ref, append `#ref` to the source:
|
|
|
|
```shell
|
|
npx quartz plugin add github:username/repo#my-branch
|
|
npx quartz plugin add git+https://github.com/username/repo.git#my-branch
|
|
npx quartz plugin add https://github.com/username/repo.git#my-branch
|
|
```
|
|
|
|
When a branch is specified, it is stored in the lockfile. All subsequent commands (`install`, `update`, `restore`, `check`, `resolve`) will respect that branch automatically.
|
|
|
|
### remove
|
|
|
|
Remove an installed plugin.
|
|
|
|
```shell
|
|
npx quartz plugin remove plugin-name
|
|
```
|
|
|
|
### install
|
|
|
|
Install all plugins listed in your `quartz.lock.json` file. This is useful when setting up the project on a new machine.
|
|
|
|
```shell
|
|
npx quartz plugin install
|
|
```
|
|
|
|
### update
|
|
|
|
Update specific plugins or all plugins to their latest versions.
|
|
|
|
```shell
|
|
npx quartz plugin update plugin-name
|
|
npx quartz plugin update # updates all
|
|
```
|
|
|
|
### restore
|
|
|
|
Restore plugins to the exact versions specified in the lockfile. Unlike `install`, this will downgrade plugins if the lockfile specifies an older version. This is recommended for CI/CD environments.
|
|
|
|
```shell
|
|
npx quartz plugin restore
|
|
```
|
|
|
|
### enable / disable
|
|
|
|
Toggle a plugin's status in your `quartz.config.yaml` without removing its files.
|
|
|
|
```shell
|
|
npx quartz plugin enable plugin-name
|
|
npx quartz plugin disable plugin-name
|
|
```
|
|
|
|
### config
|
|
|
|
View or modify the configuration for a specific plugin.
|
|
|
|
```shell
|
|
# View config
|
|
npx quartz plugin config plugin-name
|
|
|
|
# Set a value
|
|
npx quartz plugin config plugin-name --set key=value
|
|
```
|
|
|
|
### check
|
|
|
|
Check if any of your installed plugins have updates available.
|
|
|
|
```shell
|
|
npx quartz plugin check
|
|
```
|
|
|
|
### prune
|
|
|
|
Remove installed plugins that are no longer referenced in your `quartz.config.yaml`. This is useful for cleaning up after removing plugin entries from your configuration.
|
|
|
|
```shell
|
|
npx quartz plugin prune
|
|
```
|
|
|
|
Use `--dry-run` to preview which plugins would be removed without making changes:
|
|
|
|
```shell
|
|
npx quartz plugin prune --dry-run
|
|
```
|
|
|
|
### resolve
|
|
|
|
Install plugins that are listed in your `quartz.config.yaml` but missing from the lockfile. This is the inverse of `prune` — it ensures your installed plugins match your configuration.
|
|
|
|
```shell
|
|
npx quartz plugin resolve
|
|
```
|
|
|
|
Use `--dry-run` to preview which plugins would be installed without making changes:
|
|
|
|
```shell
|
|
npx quartz plugin resolve --dry-run
|
|
```
|
|
|
|
## Common Workflows
|
|
|
|
### Adding and Enabling a Plugin
|
|
|
|
To add a new plugin and start using it:
|
|
|
|
1. Add the plugin: `npx quartz plugin add github:quartz-community/example`
|
|
2. Enable it: `npx quartz plugin enable example`
|
|
|
|
### Updating Everything
|
|
|
|
To keep your plugins fresh:
|
|
|
|
```shell
|
|
npx quartz plugin update
|
|
```
|
|
|
|
### Managing Configuration
|
|
|
|
If you want to change a plugin setting without opening the YAML file:
|
|
|
|
```shell
|
|
npx quartz plugin config explorer --set useSavedState=true
|
|
```
|
|
|
|
### Cleaning Up Unused Plugins
|
|
|
|
If you've removed plugins from your config and want to clean up leftover files:
|
|
|
|
```shell
|
|
npx quartz plugin prune --dry-run # preview first
|
|
npx quartz plugin prune # remove orphaned plugins
|
|
```
|
|
|
|
### Setting Up from Config
|
|
|
|
When setting up on a new machine or in CI, resolve any plugins referenced in your config that aren't yet installed:
|
|
|
|
```shell
|
|
npx quartz plugin resolve
|
|
```
|
|
|
|
### Testing with Branches
|
|
|
|
If a plugin author has a fix or feature on a separate branch, you can install it directly without waiting for a release to the default branch:
|
|
|
|
```shell
|
|
# Install from a feature branch
|
|
npx quartz plugin add github:username/repo#fix/some-bug
|
|
|
|
# Later, switch back to the default branch by re-adding without a ref
|
|
npx quartz plugin remove repo
|
|
npx quartz plugin add github:username/repo
|
|
```
|
|
|
|
The branch ref is tracked in `quartz.lock.json`, so `update` and `check` will continue to follow the specified branch until the plugin is re-added without one.
|
|
|
|
Both `prune` and `resolve` will fall back to `quartz.config.default.yaml` if no `quartz.config.yaml` is present.
|
|
|
|
## Interactive Mode
|
|
|
|
Running the plugin command without any subcommand will launch the [[cli/tui|TUI]], which provides a visual interface for all these operations.
|
|
|
|
```shell
|
|
npx quartz plugin
|
|
```
|