feat: support npm scoped package specifiers for plugins

Plugins can now be referenced as "@quartz-community/<name>" in
quartz.config.yaml and via 'quartz plugin add'. The npm path skips
git installation and resolves from node_modules.

Changes:
- gitLoader.ts: detect @scope/name as npm package in parsePluginSource()
- config-loader.ts: skip git install for npm packages, read manifests
  from node_modules via createRequire
- install-plugins.ts: filter npm packages from prebuild, fallback to
  YAML config parsing to avoid loading full quartz.ts
- plugin-data.js: npm detection in CLI parseGitSource()
- plugin-git-handlers.js: npm install path in handlePluginAdd()
- package.json: add missing hast-util-from-html dependency

quartz/cli/plugin-data.js

@@ -190,6 +190,11 @@ export function parseGitSource(source) {
       typeof source === "object" && source.name ? source.name : path.basename(parsed, ".git")
     return { name, url: parsed, ref, subdir }
   }
+  // Handle npm scoped packages
+  if (typeof url === "string" && url.startsWith("@") && url.includes("/") && !url.includes(":")) {
+    const name = typeof source === "object" && source.name ? source.name : url
+    return { name, url: "", npmPackage: true, subdir }
+  }
   throw new Error(`Cannot parse plugin source: ${formatSource(source)}`)
 }
 

quartz/cli/plugin-git-handlers.js

@@ -1,7 +1,7 @@
 import fs from "fs"
 import path from "path"
 import os from "os"
-import { exec as execCb } from "child_process"
+import { exec as execCb, execSync } from "child_process"
 import { styleText, promisify } from "util"
 import {
   readPluginsJson,
@@ -1190,6 +1190,15 @@ export async function handlePluginAdd(
   for (const source of sources) {
     try {
       const parsed = parseGitSource(source)
+      if (parsed.npmPackage) {
+        const name = nameOverride ?? parsed.name
+        console.log(styleText("cyan", `→ Installing ${name} from npm...`))
+        execSync(`npm install ${parsed.name}`, { cwd: process.cwd(), stdio: "inherit" })
+        const configSource = nameOverride ? { repo: parsed.name, name: nameOverride } : parsed.name
+        const pluginDir = path.join(process.cwd(), "node_modules", ...parsed.name.split("/"))
+        addedPlugins.push({ name, pluginDir, source: parsed.name, configSource })
+        continue
+      }
       const name = nameOverride ?? parsed.name
       const url = parsed.url
       const ref = parsed.ref

quartz/plugins/loader/config-loader.ts

@@ -2,6 +2,7 @@ import fs from "fs"
 import path from "path"
 import YAML from "yaml"
 import { styleText } from "util"
+import { createRequire } from "node:module"
 import { QuartzConfig, GlobalConfiguration, FullPageLayout } from "../../cfg"
 import { QuartzComponent, QuartzComponentConstructor } from "../../components/types"
 import { PluginTypes } from "../types"
@@ -200,8 +201,14 @@ async function resolvePluginManifest(source: PluginSource): Promise<PluginManife
 async function readManifestFromPackageJson(source: PluginSource): Promise<PluginManifest | null> {
   try {
     const gitSpec = parsePluginSource(source)
-    const pluginDir = path.join(process.cwd(), ".quartz", "plugins", gitSpec.name)
-    const pkgPath = path.join(pluginDir, "package.json")
+    const require = createRequire(import.meta.url)
+    let pkgPath: string
+    if (gitSpec.npmPackage) {
+      pkgPath = require.resolve(`${gitSpec.name}/package.json`, { paths: [process.cwd()] })
+    } else {
+      const pluginDir = path.join(process.cwd(), ".quartz", "plugins", gitSpec.name)
+      pkgPath = path.join(pluginDir, "package.json")
+    }
     if (!fs.existsSync(pkgPath)) return null
 
     const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"))
@@ -259,6 +266,9 @@ export async function loadQuartzConfig(
   for (const entry of enabledEntries) {
     try {
       const gitSpec = parsePluginSource(entry.source)
+      if (gitSpec.npmPackage) {
+        continue
+      }
       const result = await installPlugin(gitSpec, { verbose: false })
       if (result.nativeDeps.size > 0) {
         allNativeDeps.set(gitSpec.name, result.nativeDeps)

quartz/plugins/loader/gitLoader.ts

@@ -31,6 +31,8 @@ export interface GitPluginSpec {
   subdir?: string
   /** Whether this is a local path source */
   local?: boolean
+  /** Whether this is an npm package (installed in node_modules) */
+  npmPackage?: boolean
 }
 
 export type PluginInstallSource = string | GitPluginSpec
@@ -87,6 +89,7 @@ export function parsePluginSource(source: PluginSource): GitPluginSpec {
       ref: ref || expanded.ref || undefined,
       subdir,
       local: expanded.local,
+      npmPackage: expanded.npmPackage,
     }
   }
 
@@ -129,6 +132,11 @@ export function parsePluginSource(source: PluginSource): GitPluginSpec {
     return { name, repo: url, ref: ref || undefined }
   }
 
+  // Handle npm scoped packages (e.g. @quartz-community/syntax-highlighting)
+  if (typeof source === "string" && source.startsWith("@") && source.includes("/") && !source.includes(":")) {
+    return { name: source, repo: "", npmPackage: true }
+  }
+
   // Assume it's a plain repo name and try github
   const parts = source.split("/")
   if (parts.length === 2) {

quartz/plugins/loader/install-plugins.ts

@@ -1,19 +1,68 @@
 #!/usr/bin/env node
+import fs from "fs"
+import path from "path"
+import YAML from "yaml"
 import { installPlugins, parsePluginSource } from "./gitLoader.js"
-import config from "../../../quartz.js"
+import type { PluginSource, QuartzPluginsJson } from "./types.js"
+
+function resolveConfigPath(): string {
+  const configYamlPath = path.join(process.cwd(), "quartz.config.yaml")
+  const defaultConfigYamlPath = path.join(process.cwd(), "quartz.config.default.yaml")
+  const legacyPluginsJsonPath = path.join(process.cwd(), "quartz.plugins.json")
+  const legacyDefaultPluginsJsonPath = path.join(process.cwd(), "quartz.plugins.default.json")
+
+  if (fs.existsSync(configYamlPath)) return configYamlPath
+  if (fs.existsSync(legacyPluginsJsonPath)) return legacyPluginsJsonPath
+  if (fs.existsSync(defaultConfigYamlPath)) return defaultConfigYamlPath
+  if (fs.existsSync(legacyDefaultPluginsJsonPath)) return legacyDefaultPluginsJsonPath
+  return configYamlPath
+}
+
+function readPluginsJson(): QuartzPluginsJson | null {
+  const configPath = resolveConfigPath()
+  if (!fs.existsSync(configPath)) return null
+  const raw = fs.readFileSync(configPath, "utf-8")
+  if (configPath.endsWith(".yaml") || configPath.endsWith(".yml")) {
+    return YAML.parse(raw)
+  }
+  return JSON.parse(raw)
+}
+
+async function getExternalPluginSources(): Promise<PluginSource[]> {
+  try {
+    const module = await import("../../../quartz.js")
+    const config = module.default ?? module
+    const externalPlugins = config.externalPlugins
+    if (Array.isArray(externalPlugins) && externalPlugins.length > 0) {
+      return externalPlugins as PluginSource[]
+    }
+  } catch {
+    // fall back to config yaml parsing
+  }
+
+  const pluginsJson = readPluginsJson()
+  const entries = pluginsJson?.plugins ?? []
+  return entries.filter((entry) => entry.enabled !== false).map((entry) => entry.source)
+}
 
 async function main() {
-  const quartzConfig: any = config
-  const externalPlugins = quartzConfig.externalPlugins || []
+  const externalPlugins = await getExternalPluginSources()
 
   if (externalPlugins.length === 0) {
     console.log("No external plugins to install.")
     return
   }
 
-  console.log(`Installing ${externalPlugins.length} plugin(s) from Git...`)
+  const specs = externalPlugins
+    .map((source: PluginSource) => parsePluginSource(source))
+    .filter((spec) => !spec.npmPackage)
 
-  const specs = externalPlugins.map((source: string) => parsePluginSource(source))
+  if (specs.length === 0) {
+    console.log("No external Git plugins to install.")
+    return
+  }
+
+  console.log(`Installing ${specs.length} plugin(s) from Git...`)
   const installed = await installPlugins(specs, { verbose: true })
 
   if (installed.size === externalPlugins.length) {