docs: updated cli commands
This commit is contained in:
saberzero1
+2
-4
@@ -14,8 +14,7 @@ You can run the CLI using `npx quartz`.
|
||||
| `build` | Generate static HTML files | `npx quartz build` |
|
||||
| `sync` | Sync content with GitHub | `npx quartz sync` |
|
||||
| `upgrade` | Upgrade Quartz to the latest version | `npx quartz upgrade` |
|
||||
| `update` | Update installed plugins | `npx quartz update` |
|
||||
| `plugin` | Manage Quartz plugins | `npx quartz plugin list` |
|
||||
| `plugin` | Manage Quartz plugins (install, add, remove, etc.) | `npx quartz plugin list` |
|
||||
| `tui` | Launch the interactive plugin manager | `npx quartz tui` |
|
||||
|
||||
## Commands
|
||||
@@ -24,10 +23,9 @@ You can run the CLI using `npx quartz`.
|
||||
- [[cli/build|build]]: Build your Quartz site into static HTML. Includes a development server.
|
||||
- [[cli/sync|sync]]: Push and pull changes between your local machine and GitHub.
|
||||
- [[cli/upgrade|upgrade]]: Upgrade the Quartz framework to the latest version.
|
||||
- [[cli/update|update]]: Update installed plugins to their latest versions.
|
||||
- [[cli/restore|restore]]: Recover your content folder from the local cache.
|
||||
- [[cli/migrate|migrate]]: Convert older configuration files to the new YAML format.
|
||||
- [[cli/plugin|plugin]]: Install, add, remove, prune, resolve, and configure plugins from the command line.
|
||||
- [[cli/plugin|plugin]]: Install, add, remove, prune, and configure plugins. Use `plugin install` with flags for lockfile/config sync, updates, and checks.
|
||||
- [[cli/tui|tui]]: Use a terminal interface to manage plugins and layout.
|
||||
|
||||
## Help and Versioning
|
||||
|
||||
+37
-43
@@ -42,7 +42,7 @@ npx quartz plugin add /absolute/path/to/plugin
|
||||
|
||||
Local plugins are symlinked into `.quartz/plugins/`, so any changes you make to the source directory are reflected immediately without re-installing.
|
||||
|
||||
When a branch is specified, it is stored in the lockfile. All subsequent commands (`install`, `update`, `restore`, `check`, `resolve`) will respect that branch automatically.
|
||||
When a branch is specified, it is stored in the lockfile. All subsequent commands (`install`, `prune`) will respect that branch automatically. Use `install --latest` to fetch the latest commit from that branch.
|
||||
|
||||
### remove
|
||||
|
||||
@@ -54,27 +54,29 @@ 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.
|
||||
Install plugins for your Quartz project. By default, this installs all plugins listed in your `quartz.lock.json` file.
|
||||
|
||||
```shell
|
||||
npx quartz plugin install
|
||||
```
|
||||
|
||||
### update
|
||||
#### Flags
|
||||
|
||||
Update specific plugins or all plugins to their latest versions.
|
||||
- `--from-config`: Synchronize plugins with `quartz.config.yaml` instead of the lockfile. This will install missing plugins and prune orphaned ones.
|
||||
- `--latest`: Fetch the latest version of plugins from their remote sources instead of using the version in the lockfile.
|
||||
- `--clean`: Skip existing directories and perform a fresh installation.
|
||||
- `--dry-run`: Preview the changes without actually installing or removing any files.
|
||||
|
||||
#### Positional Arguments
|
||||
|
||||
- `[names..]`: Optional list of specific plugin names to install or update.
|
||||
|
||||
```shell
|
||||
npx quartz plugin update plugin-name
|
||||
npx quartz plugin update # updates all
|
||||
```
|
||||
# Update specific plugins to latest
|
||||
npx quartz plugin install --latest plugin-a plugin-b
|
||||
|
||||
### 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
|
||||
# Preview what would be installed from config
|
||||
npx quartz plugin install --from-config --dry-run
|
||||
```
|
||||
|
||||
### enable / disable
|
||||
@@ -98,20 +100,12 @@ npx quartz plugin config plugin-name
|
||||
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.
|
||||
|
||||
> [!note]
|
||||
> The `resolve` command also removes orphaned plugins as part of its synchronization. Use `prune` when you only want to clean up without installing anything new.
|
||||
> Running `plugin install --from-config` also removes orphaned plugins as part of its synchronization. Use `prune` when you only want to clean up without installing anything new.
|
||||
|
||||
```shell
|
||||
npx quartz plugin prune
|
||||
@@ -123,20 +117,6 @@ Use `--dry-run` to preview which plugins would be removed without making changes
|
||||
npx quartz plugin prune --dry-run
|
||||
```
|
||||
|
||||
### resolve
|
||||
|
||||
Synchronize your installed plugins with your `quartz.config.yaml`. This installs plugins that are in your config but missing from the lockfile, and removes plugins that are in the lockfile but no longer referenced in your config.
|
||||
|
||||
```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
|
||||
@@ -151,7 +131,7 @@ To add a new plugin and start using it:
|
||||
To keep your plugins fresh:
|
||||
|
||||
```shell
|
||||
npx quartz plugin update
|
||||
npx quartz plugin install --latest
|
||||
```
|
||||
|
||||
### Managing Configuration
|
||||
@@ -173,10 +153,10 @@ npx quartz plugin prune # remove orphaned plugins
|
||||
|
||||
### Setting Up from Config
|
||||
|
||||
When setting up on a new machine or in CI, resolve ensures your installed plugins match your config — installing missing plugins and removing any that are no longer referenced:
|
||||
When setting up on a new machine or in CI, `install --from-config` ensures your installed plugins match your config — installing missing plugins and removing any that are no longer referenced:
|
||||
|
||||
```shell
|
||||
npx quartz plugin resolve
|
||||
npx quartz plugin install --from-config
|
||||
```
|
||||
|
||||
### Testing with Branches
|
||||
@@ -192,9 +172,9 @@ 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.
|
||||
The branch ref is tracked in `quartz.lock.json`, so `install --latest` 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.
|
||||
Both `prune` and `install --from-config` will fall back to `quartz.config.default.yaml` if no `quartz.config.yaml` is present.
|
||||
|
||||
### Local Plugin Development
|
||||
|
||||
@@ -204,7 +184,7 @@ For local plugin development or airgapped environments, you can add a plugin fro
|
||||
npx quartz plugin add ./my-local-plugin
|
||||
```
|
||||
|
||||
Local plugins are symlinked into `.quartz/plugins/`, so changes reflect immediately. When you run `update`, local plugins are rebuilt (npm install + npm run build) without any git operations. The `check` command will show local plugins with a "local" status instead of checking for remote updates.
|
||||
Local plugins are symlinked into `.quartz/plugins/`, so changes reflect immediately. When you run `install --latest`, local plugins are rebuilt (npm install + npm run build) without any git operations. The `install --latest --dry-run` command will show local plugins with a "local" status instead of checking for remote updates.
|
||||
|
||||
To switch a local plugin back to a git source:
|
||||
|
||||
@@ -242,7 +222,21 @@ plugins:
|
||||
See [[configuration#Advanced Source Options|Advanced Source Options]] for the full reference on object source fields.
|
||||
|
||||
> [!note]
|
||||
> The `plugin add` CLI command works with string sources. To use the object source format with `subdir`, edit `quartz.config.yaml` directly, then run `npx quartz plugin resolve` to install it.
|
||||
> The `plugin add` CLI command works with string sources. To use the object source format with `subdir`, edit `quartz.config.yaml` directly, then run `npx quartz plugin install --from-config` to install it.
|
||||
|
||||
## Migration from Deprecated Commands
|
||||
|
||||
| Old command | New equivalent |
|
||||
| ------------------------------------- | --------------------------------------------------- |
|
||||
| `npx quartz plugin restore` | `npx quartz plugin install --clean` |
|
||||
| `npx quartz plugin update` | `npx quartz plugin install --latest` |
|
||||
| `npx quartz plugin update my-plugin` | `npx quartz plugin install --latest my-plugin` |
|
||||
| `npx quartz plugin check` | `npx quartz plugin install --latest --dry-run` |
|
||||
| `npx quartz plugin resolve` | `npx quartz plugin install --from-config` |
|
||||
| `npx quartz plugin resolve --dry-run` | `npx quartz plugin install --from-config --dry-run` |
|
||||
| `npx quartz update` | `npx quartz plugin install --latest` |
|
||||
|
||||
The old commands still work as hidden aliases but will print a deprecation warning.
|
||||
|
||||
## Interactive Mode
|
||||
|
||||
|
||||
+3
-1
@@ -2,7 +2,9 @@
|
||||
title: quartz restore
|
||||
---
|
||||
|
||||
The `restore` command is a safety mechanism that allows you to recover your content folder from a local cache.
|
||||
The `restore` command is a safety mechanism that allows you to recover your **content folder** from a local cache. This command only affects your Markdown files and does not restore plugins or configuration.
|
||||
|
||||
To restore plugins to a specific state, use [[cli/plugin|npx quartz plugin install]].
|
||||
|
||||
## When to Use
|
||||
|
||||
|
||||
@@ -1,38 +0,0 @@
|
||||
---
|
||||
title: quartz update
|
||||
---
|
||||
|
||||
The `update` command updates your installed plugins to their latest versions. It is a convenient shortcut for `npx quartz plugin update`.
|
||||
|
||||
## Usage
|
||||
|
||||
Update all installed plugins:
|
||||
|
||||
```shell
|
||||
npx quartz update
|
||||
```
|
||||
|
||||
Update specific plugins by name:
|
||||
|
||||
```shell
|
||||
npx quartz update my-plugin another-plugin
|
||||
```
|
||||
|
||||
## How it Works
|
||||
|
||||
For each plugin, `update` fetches the latest commit from the plugin's remote repository and rebuilds it. If a plugin was installed from a specific branch (e.g., `github:user/repo#my-branch`), updates will track that branch instead of the default branch. Local plugins (added from a file path) are rebuilt without any git operations. The lockfile (`quartz.lock.json`) is updated with the new commit hashes.
|
||||
|
||||
This is functionally identical to running:
|
||||
|
||||
```shell
|
||||
npx quartz plugin update
|
||||
```
|
||||
|
||||
## Flags
|
||||
|
||||
The `update` command supports the standard [[cli/index|common flags]] (`--directory`, `--verbose`).
|
||||
|
||||
## See Also
|
||||
|
||||
- [[cli/upgrade|quartz upgrade]] — upgrade the Quartz framework itself
|
||||
- [[cli/plugin|quartz plugin]] — full plugin management (install, remove, enable, disable, etc.)
|
||||
+1
-1
@@ -43,6 +43,6 @@ The `upgrade` command supports the standard [[cli/index|common flags]] (`--direc
|
||||
|
||||
## See Also
|
||||
|
||||
- [[cli/update|quartz update]] — update installed plugins
|
||||
- [[cli/plugin|quartz plugin install --latest]] — update installed plugins
|
||||
- [[getting-started/upgrading|Upgrading Quartz]] — detailed upgrading guide
|
||||
- [[cli/restore|quartz restore]] — recover content from cache
|
||||
|
||||
Reference in New Issue
Block a user