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

docs: updated cli commands

Browse Source
This commit is contained in:
saberzero1
2026-03-31 18:50:38 +02:00
parent db2cc6abca
commit 04912ac2e5
14 changed files with 67 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/advanced/architecture.md
View File

@@ -77,8 +77,8 @@ When `npx quartz plugin add github:quartz-community/explorer` is run:
### Plugin CLI Commands
- `npx quartz plugin add github:quartz-community/<name>` — Install a community plugin
- `npx quartz plugin update` — Update all plugins to latest commits
- `npx quartz plugin restore` — Restore plugins from locked commits in `quartz.lock.json` (used in CI/CD)
- `npx quartz plugin install --latest` — Update all plugins to latest commits
- `npx quartz plugin install --clean` — Restore plugins from locked commits in `quartz.lock.json` (used in CI/CD)
- `npx quartz plugin remove <name>` — Remove an installed plugin
### Plugin Structure

4
docs/advanced/making plugins.md
View File

@@ -514,10 +514,10 @@ If you've updated your `quartz.config.yaml` to reference a plugin that isn't ins
```shell
# Install all config-referenced plugins missing from the lockfile
npx quartz plugin resolve
npx quartz plugin install --from-config
# Preview first without making changes
npx quartz plugin resolve --dry-run
npx quartz plugin install --from-config --dry-run
```
To clean up plugins that are installed but no longer referenced in your config:

6
docs/cli/index.md
View File

@@ -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

80
docs/cli/plugin.md
View File

@@ -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

4
docs/cli/restore.md
View File

@@ -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

38
docs/cli/update.md
View File

@@ -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.)

2
docs/cli/upgrade.md
View File

@@ -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

2
docs/community.md
View File

@@ -12,7 +12,7 @@ Quartz has a vibrant community of users and contributors. This page highlights c
Third-party plugins that extend Quartz functionality. Install them with the [[cli/plugin|plugin CLI]]:
```bash
npx quartz plugin install <github-url>
npx quartz plugin add <github-url>
```
<!-- Add community plugins here as they become available -->

2
docs/configuration.md
View File

@@ -145,7 +145,7 @@ 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
npx quartz plugin install --from-config
```
To remove installed plugins that are no longer in your config:

14
docs/getting-started/migrating.md
View File

@@ -39,7 +39,7 @@ Available templates: `default`, `obsidian`, `ttrpg`, `blog`. Pick the one closes
After running `create`, install all the plugins referenced in the generated config:
```shell
npx quartz plugin resolve
npx quartz plugin install --from-config
```
This reads your `quartz.config.yaml` and installs every plugin listed in it. No need to run 30 individual `npx quartz plugin add` commands.
@@ -57,7 +57,7 @@ This reads your `quartz.config.yaml` and installs every plugin listed in it. No
> See [[plugins/index|Plugins]] for the full list of available community plugins.
> [!info] Alternative: Use `npx quartz migrate`
> If you have an existing `quartz.config.ts` and `quartz.layout.ts` from v4, you can run `npx quartz migrate` instead. This reads your old config files and generates `quartz.config.yaml` with your existing settings. You'll still need to run `npx quartz plugin resolve` afterward to install the plugins. See [[cli/migrate|quartz migrate]] for details.
> If you have an existing `quartz.config.ts` and `quartz.layout.ts` from v4, you can run `npx quartz migrate` instead. This reads your old config files and generates `quartz.config.yaml` with your existing settings. You'll still need to run `npx quartz plugin install --from-config` afterward to install the plugins. See [[cli/migrate|quartz migrate]] for details.
#### 2. Update quartz.config.yaml
@@ -254,13 +254,13 @@ Key changes:
#### 4. Update CI/CD
Add `npx quartz plugin restore` to your build pipeline, before `npx quartz build`. This installs plugins from the lockfile at their pinned versions.
Add `npx quartz plugin install` 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:
If your CI uses `quartz.config.default.yaml` (or contributors may add plugins to config without updating the lockfile), also run `npx quartz plugin install --from-config` 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 plugin install # install pinned plugins from lockfile
npx quartz plugin install --from-config # install any config-referenced plugins not yet in lockfile
npx quartz build
```
@@ -326,7 +326,7 @@ git fetch
git checkout v4
git pull upstream v4
npm i
npx quartz plugin restore
npx quartz plugin install
npx quartz create
```

2
docs/getting-started/upgrading.md
View File

@@ -23,7 +23,7 @@ If you have the [GitHub desktop app](https://desktop.github.com/), this will aut
To update your installed plugins separately, use:
```bash
npx quartz update
npx quartz plugin install --latest
```
See the [[cli/update|CLI reference for update]] and [[cli/upgrade|CLI reference for upgrade]] for more details on available flags.

14
docs/hosting.md
View File

@@ -13,7 +13,7 @@ However, if you'd like to publish your site to the world, you need a way to host
> 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.
> All hosting examples below use `npx quartz plugin install` to install plugins from the lockfile. If contributors may add plugins to `quartz.config.yaml` without updating the lockfile, add `npx quartz plugin install --from-config` after `restore` in your build command to install any missing plugins. See [[cli/plugin#resolve|plugin resolve]] for details.
## Cloudflare Pages
@@ -25,7 +25,7 @@ However, if you'd like to publish your site to the world, you need a way to host
| ---------------------- | ----------------------------------------------- |
| Production branch | `v5` |
| Framework preset | `None` |
| Build command | `npx quartz plugin restore && npx quartz build` |
| Build command | `npx quartz plugin install && npx quartz build` |
| Build output directory | `public` |
Press "Save and deploy" and Cloudflare should have a deployed version of your site in about a minute. Then, every time you sync your Quartz changes to GitHub, your site should be updated.
@@ -33,7 +33,7 @@ Press "Save and deploy" and Cloudflare should have a deployed version of your si
To add a custom domain, check out [Cloudflare's documentation](https://developers.cloudflare.com/pages/platform/custom-domains/).
> [!warning]
> Cloudflare Pages performs a shallow clone by default, so if you rely on `git` for timestamps, it is recommended that you add `git fetch --unshallow &&` to the beginning of the build command (e.g., `git fetch --unshallow && npx quartz plugin restore && npx quartz build`).
> Cloudflare Pages performs a shallow clone by default, so if you rely on `git` for timestamps, it is recommended that you add `git fetch --unshallow &&` to the beginning of the build command (e.g., `git fetch --unshallow && npx quartz plugin install && npx quartz build`).
> [!note]
> For more detailed CI/CD configuration including caching and plugin management, see [[ci-cd]].
@@ -72,7 +72,7 @@ jobs:
- name: Install Dependencies
run: npm ci
- name: Restore Quartz plugins
run: npx quartz plugin restore
run: npx quartz plugin install
- name: Build Quartz
run: npx quartz build
- name: Upload artifact
@@ -152,7 +152,7 @@ Before deploying to Vercel, a `vercel.json` file is required at the root of the
| ----------------------------------------- | ----------------------------------------------- |
| Framework Preset | `Other` |
| Root Directory | `./` |
| Build and Output Settings > Build Command | `npx quartz plugin restore && npx quartz build` |
| Build and Output Settings > Build Command | `npx quartz plugin install && npx quartz build` |
5. Press Deploy. Once it's live, you'll have 2 `*.vercel.app` URLs to view the page.
@@ -183,7 +183,7 @@ Using `docs.example.com` is an example of a subdomain. They're a simple way of c
1. Log in to the [Netlify dashboard](https://app.netlify.com/) and click "Add new site".
2. Select your Git provider and repository containing your Quartz project.
3. Under "Build command", enter `npx quartz plugin restore && npx quartz build`.
3. Under "Build command", enter `npx quartz plugin install && npx quartz build`.
4. Under "Publish directory", enter `public`.
5. Press Deploy. Once it's live, you'll have a `*.netlify.app` URL to view the page.
6. To add a custom domain, check "Domain management" in the left sidebar, just like with Vercel.
@@ -211,7 +211,7 @@ build:
- hash -r
- npm ci --cache .npm --prefer-offline
script:
- npx quartz plugin restore
- npx quartz plugin install
- npx quartz build
artifacts:
paths:

2
docs/index.md
View File

@@ -14,7 +14,7 @@ Then, in your terminal of choice, enter the following commands line by line:
git clone -b v5 https://github.com/jackyzha0/quartz.git
cd quartz
npm i
npx quartz plugin restore
npx quartz plugin install
npx quartz create
```

4
docs/troubleshooting.md
View File

@@ -11,7 +11,7 @@ Common issues and solutions when working with Quartz.
This usually means a plugin is not installed. Run:
```bash
npx quartz plugin restore
npx quartz plugin install
```
This restores all plugins from your `quartz.lock.json` to `.quartz/plugins/`.
@@ -37,7 +37,7 @@ The default uses all available CPU cores. If you're on a memory-constrained envi
1. Verify the plugin appears in `quartz.config.yaml` under `plugins:`
2. Check that `enabled: true` is set
3. Run `npx quartz plugin list` to confirm it's installed
4. Run `npx quartz plugin check` to verify plugin health
4. Run `npx quartz plugin install --latest --dry-run` to verify plugin health
### Plugin options not taking effect