Quartz Community Plugin Template

Production-ready template for building, testing, and publishing Quartz community plugins. It mirrors Quartz's native plugin patterns and uses a factory-function API similar to Astro integrations: plugins are created by functions that return objects with name and lifecycle hooks.

Highlights

• ✅ Quartz-compatible transformer/filter/emitter examples
• ✅ TypeScript-first with exported types for consumers
• ✅ tsup bundling + declaration output
• ✅ Vitest testing setup with example tests
• ✅ Linting/formatting with ESLint + Prettier
• ✅ CI workflow for checks and npm publishing
• ✅ Demonstrates CSS/JS resource injection and remark/rehype usage

Getting started

npm install
npm run build

Usage in Quartz

Install your plugin into a Quartz v5 site:

npx quartz plugin add github:quartz-community/plugin-template

Then register it in quartz.config.ts:

import * as ExternalPlugin from "./.quartz/plugins";

export default {
  configuration: {
    pageTitle: "My Garden",
  },
  plugins: {
    transformers: [ExternalPlugin.ExampleTransformer({ highlightToken: "==" })],
    filters: [ExternalPlugin.ExampleFilter({ allowDrafts: false })],
    emitters: [ExternalPlugin.ExampleEmitter({ manifestSlug: "plugin-manifest" })],
  },
  externalPlugins: ["github:quartz-community/plugin-template"],
};

Plugin factory pattern (Astro-style)

Quartz plugins are factory functions that return an object with a name and hook implementations. This mirrors Astro's integration pattern (a function returning an object of hooks), which makes composition and configuration explicit and predictable.

import type { QuartzTransformerPlugin } from "@quartz-community/types";

export const MyTransformer: QuartzTransformerPlugin<{ enabled: boolean }> = (opts) => {
  return {
    name: "MyTransformer",
    markdownPlugins() {
      return [];
    },
  };
};

Examples included

Transformer

ExampleTransformer shows how to:

• apply a custom remark plugin
• run a rehype plugin
• inject CSS/JS resources
• perform a text transform hook

import { ExampleTransformer } from "@quartz-community/plugin-template";

ExampleTransformer({
  highlightToken: "==",
  headingClass: "example-plugin-heading",
  enableGfm: true,
  addHeadingSlugs: true,
});

The transformer uses a custom remark plugin to convert ==highlight== into bold text and a rehype plugin to attach a class to all headings. It also injects a small inline CSS/JS snippet.

Filter

ExampleFilter demonstrates frontmatter-driven filtering:

ExampleFilter({
  allowDrafts: false,
  excludeTags: ["private", "wip"],
  excludePathPrefixes: ["_drafts/", "_private/"],
});

Emitter

ExampleEmitter emits a JSON manifest of all pages:

ExampleEmitter({
  manifestSlug: "plugin-manifest",
  includeFrontmatter: true,
  metadata: { project: "My Garden" },
  transformManifest: (json) => json.replace("My Garden", "Quartz"),
});

API reference

ExampleTransformer(options)

| Option | Type | Default | Description | | ----------------- | --------- | -------------------------- | ----------------------------- | | highlightToken | string | "==" | Token used to highlight text. | | headingClass | string | "example-plugin-heading" | Class added to headings. | | enableGfm | boolean | true | Enables remark-gfm. | | addHeadingSlugs | boolean | true | Enables rehype-slug. |

ExampleFilter(options)

| Option | Type | Default | Description | | --------------------- | ---------- | --------------------------- | ------------------------- | | allowDrafts | boolean | false | Publish draft pages. | | excludeTags | string[] | ["private"] | Tags to exclude. | | excludePathPrefixes | string[] | ["_drafts/", "_private/"] | Path prefixes to exclude. |

ExampleEmitter(options)

| Option | Type | Default | Description | | --------------------- | -------------------------- | ----------------------------------------- | ----------------------------------------- | | manifestSlug | string | "plugin-manifest" | Output filename (without extension). | | includeFrontmatter | boolean | true | Include frontmatter in output. | | metadata | Record<string, unknown> | { generator: "Quartz Plugin Template" } | Extra metadata in manifest. | | transformManifest | (json: string) => string | undefined | Custom transformer for emitted JSON. | | manifestScriptClass | string | undefined | Optional CSS class if rendered into HTML. |

Testing

npm test

Build and lint

npm run build
npm run lint
npm run format

Publishing

Tags matching v* trigger the GitHub Actions publish workflow. Ensure NPM_TOKEN is set in the repository secrets.

Component Plugins (UI Components)

In addition to transformer/filter/emitter plugins, you can create component plugins that provide UI elements for Quartz layouts. See src/components/ExampleComponent.tsx for a reference.

Component Pattern

import type { QuartzComponent, QuartzComponentConstructor } from "@quartz-community/types";
import style from "./styles/example.scss";
import script from "./scripts/example.inline.ts";

export default ((opts?: MyComponentOptions) => {
  const Component: QuartzComponent = (props) => {
    return <div class="my-component">...</div>;
  };

  Component.css = style;
  Component.afterDOMLoaded = script;

  return Component;
}) satisfies QuartzComponentConstructor;

Receiving YAML Options in Component-Only Plugins

Processing plugins (transformers, filters, emitters, page types) receive options automatically through their factory function. Component-only plugins (those with "category": ["component"]) are loaded via side-effect import and need an extra step to receive YAML options.

Export an init function from your plugin's entry point. Quartz's config-loader will call it with the merged options from package.json defaultOptions and the user's quartz.config.yaml:

// src/index.ts
export function init(options?: Record<string, unknown>): void {
  // Use the options to configure your plugin
  const myOption = (options?.myOption as boolean) ?? false;
  // e.g. register a view, set global state, etc.
}

Then declare default values in your package.json manifest:

{
  "quartz": {
    "category": ["component"],
    "defaultOptions": {
      "myOption": false
    }
  }
}

Users configure options in quartz.config.yaml:

plugins:
  - source: github:your-username/my-component-plugin
    enabled: true
    options:
      myOption: true

Quartz merges defaultOptions with the user's options (user values take precedence) and passes the result to init(). If no init export exists, the plugin is loaded via side-effect import as before — no breaking change for existing plugins.

Client-Side Scripts

Component scripts run in the browser and must handle Quartz's SPA navigation. Key patterns:

1. Use @ts-nocheck - Client scripts run in a different context than build-time code
2. Listen to nav event - Fires after each page navigation (including initial load)
3. Listen to prenav event - Fires before navigation, use for saving state
4. Use window.addCleanup() - Register cleanup functions for event listeners
5. Use fetchData global - Access page metadata via the fetchData promise (handles base path correctly)

See src/components/scripts/example.inline.ts for a complete example with all patterns.

Common Helper Functions

These utilities are commonly needed in component plugins:

function removeAllChildren(element) {
  while (element.firstChild) element.removeChild(element.firstChild);
}

function simplifySlug(slug) {
  return slug.endsWith("/index") ? slug.slice(0, -6) : slug;
}

function getCurrentSlug() {
  let slug = window.location.pathname;
  if (slug.startsWith("/")) slug = slug.slice(1);
  if (slug.endsWith("/")) slug = slug.slice(0, -1);
  return slug || "index";
}

State Persistence

Use localStorage for persistent state (survives browser close) and sessionStorage for temporary state (like scroll positions):

localStorage.setItem("myPlugin-state", JSON.stringify(state));
sessionStorage.setItem("myPlugin-scrollTop", element.scrollTop.toString());

Migration Guide (from Quartz v4)

When migrating a v4 component to a standalone plugin:

1. Replace Quartz imports with @quartz-community/types
2. Copy utility functions (path helpers, DOM utils) into your plugin
3. Use @ts-nocheck for inline scripts that can't be type-checked
4. Use the fetchData global to access contentIndex.json with the correct base path
5. Test with both local and production builds

License

MIT