diff --git a/docs/advanced/architecture.md b/docs/advanced/architecture.md index 1bf4b52..5cb860b 100644 --- a/docs/advanced/architecture.md +++ b/docs/advanced/architecture.md @@ -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/` — 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 ` — Remove an installed plugin ### Plugin Structure diff --git a/docs/advanced/making plugins.md b/docs/advanced/making plugins.md index 5de51d0..cf9aae4 100644 --- a/docs/advanced/making plugins.md +++ b/docs/advanced/making plugins.md @@ -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: diff --git a/docs/cli/index.md b/docs/cli/index.md index 1cdf15c..f56d1e6 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -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 diff --git a/docs/cli/plugin.md b/docs/cli/plugin.md index 57bb91a..a0443d1 100644 --- a/docs/cli/plugin.md +++ b/docs/cli/plugin.md @@ -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 diff --git a/docs/cli/restore.md b/docs/cli/restore.md index ebbdeaf..ca07d77 100644 --- a/docs/cli/restore.md +++ b/docs/cli/restore.md @@ -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 diff --git a/docs/cli/update.md b/docs/cli/update.md deleted file mode 100644 index 28be49c..0000000 --- a/docs/cli/update.md +++ /dev/null @@ -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.) diff --git a/docs/cli/upgrade.md b/docs/cli/upgrade.md index b78d86d..20436e2 100644 --- a/docs/cli/upgrade.md +++ b/docs/cli/upgrade.md @@ -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 diff --git a/docs/community.md b/docs/community.md index 6c72e1c..c14a1c7 100644 --- a/docs/community.md +++ b/docs/community.md @@ -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 +npx quartz plugin add ``` diff --git a/docs/configuration.md b/docs/configuration.md index cf3b402..52520f8 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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: diff --git a/docs/getting-started/migrating.md b/docs/getting-started/migrating.md index c15539a..6b50cbc 100644 --- a/docs/getting-started/migrating.md +++ b/docs/getting-started/migrating.md @@ -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 ``` diff --git a/docs/getting-started/upgrading.md b/docs/getting-started/upgrading.md index fa17d42..e1e4f47 100644 --- a/docs/getting-started/upgrading.md +++ b/docs/getting-started/upgrading.md @@ -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. diff --git a/docs/hosting.md b/docs/hosting.md index cc6fcd0..a3ebe99 100644 --- a/docs/hosting.md +++ b/docs/hosting.md @@ -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: diff --git a/docs/index.md b/docs/index.md index 4a9c343..ff5d041 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 ``` diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index fcc15bc..339925f 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -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