Agent Control Center
Back to Directory
quartz-omp-plugin-patching

quartz-omp-plugin-patching

How to safely modify, vendor, and build local plugins within the quartz-omp YAML-configured architecture.

Quartz OMP Plugin Patching Workflow

When working with the quartz-omp ecosystem, standard Quartz 5 plugin conventions (like quartz.config.ts) do not apply. The system relies on a modular, YAML-driven plugin architecture.

1. Configuration

Always modify plugin configurations via quartz.config.yaml (or quartz.config.default.yaml), never quartz.config.ts.

2. Patching External Plugins

If an external github: plugin needs modification (e.g., github:quartz-community/article-title), it must be vendored into the local workspace:

  1. Copy the cached plugin: The install-plugins script caches github plugins in .quartz/plugins/. Copy the target plugin from .quartz/plugins/<plugin-name> to quartz/local-plugins/<plugin-name>.
  2. Update the config: Change its entry in quartz.config.yaml from source: github:quartz-community/<plugin-name> to source: ./quartz/local-plugins/<plugin-name>.

3. Building Local Plugins

Every plugin inside quartz/local-plugins/ acts as an isolated NPM package. After making edits to a local plugin's source files, you MUST:

cd quartz/local-plugins/<plugin-name>
npm install
npm run build

4. Cross-Plugin Imports (TypeScript rootDir Errors)

If you attempt to import a utility from outside the plugin's directory (e.g., import { util } from "../../../../util/helper.ts"), tsup/tsc will fail to generate .d.ts types because the import is outside the compiler's rootDir. To fix this, edit the plugin's tsconfig.json and remove the "rootDir": "." property before building.