docs: add npm plugin specifier migration guide

2026-07-23 09:38:52 +02:00
parent 3d99dca87d
commit 555b2ba838
1 changed files with 45 additions and 0 deletions
@@ -38,3 +38,48 @@ npx quartz plugin prune            # remove orphaned plugins
 ```

 See the [[cli/plugin#prune|plugin prune reference]] for more details.
+
+## Switching to npm Plugin Specifiers
+
+First-party Quartz plugins are now published to npm under the `@quartz-community` scope. If your `quartz.config.yaml` uses `github:` specifiers, you can optionally switch to npm specifiers for faster installs and better version pinning.
+
+### Why Switch?
+
+- **Faster installs**: npm packages are cached locally and don't require git cloning
+- **Version pinning**: npm uses semver ranges, so you control when to update
+- **No build step**: npm packages ship pre-built, unlike git sources which may need to build on install
+
+### How to Migrate
+
+Update each plugin source in your `quartz.config.yaml` from the `github:` format to the quoted npm format:
+
+```yaml
+# Before
+plugins:
+  - source: github:quartz-community/syntax-highlighting
+    enabled: true
+
+# After
+plugins:
+  - source: "@quartz-community/syntax-highlighting"
+    enabled: true
+```
+
+> [!important]
+> The `@` scoped name must be quoted in YAML. Use double quotes around the source value.
+
+Then install the packages:
+
+```bash
+npm install @quartz-community/syntax-highlighting
+```
+
+Or install all default plugins at once:
+
+```bash
+npm install @quartz-community/created-modified-date @quartz-community/syntax-highlighting @quartz-community/obsidian-flavored-markdown @quartz-community/github-flavored-markdown @quartz-community/table-of-contents @quartz-community/crawl-links @quartz-community/description @quartz-community/latex @quartz-community/quartz-fonts @quartz-community/remove-draft @quartz-community/alias-redirects @quartz-community/content-index @quartz-community/favicon @quartz-community/og-image @quartz-community/cname @quartz-community/canvas-page @quartz-community/content-page @quartz-community/folder-page @quartz-community/tag-page @quartz-community/explorer @quartz-community/graph @quartz-community/search @quartz-community/backlinks @quartz-community/article-title @quartz-community/content-meta @quartz-community/page-title @quartz-community/darkmode @quartz-community/reader-mode @quartz-community/breadcrumbs @quartz-community/footer @quartz-community/spacer @quartz-community/bases-page @quartz-community/note-properties @quartz-community/unlisted-pages @quartz-community/encrypted-pages
+```
+
+### Do I Have to Switch?
+
+No. The `github:` specifiers continue to work and will be supported indefinitely. They are still the recommended approach for third-party and community plugins that are not published to npm. The npm path is an optional improvement for first-party plugins.