fonts/ARCHITECTURE.md

Architecture Reference

Machine-readable architecture overview for the Quartz community plugin template.

Plugin Lifecycle

Quartz plugins are factory functions that return an object with a name and lifecycle hooks.

1. Loading: Quartz imports the plugin from the externalPlugins list in quartz.config.ts.
2. Initialization: The factory function is called with user-provided options.
3. Build Integration:
   • Transformers: Run during the transform phase (remark/rehype).
   • Filters: Run after transformation to prune the content list.
   • Emitters: Run during the emit phase to generate files.
   • Page Types: Run to generate virtual pages or custom routes.
   • Components: Rendered during the HTML generation phase.

Build System

The template uses tsup for bundling and declaration output.

• Inline Scripts: Files ending in .inline.ts are bundled as raw strings for client-side injection.
• Styles: .scss files are compiled to CSS strings and attached to components via Component.css.
• Entry Points:
  • index.ts: Main plugin exports.
  • types.ts: Shared type definitions.
  • components/index.ts: UI component exports.

Type System

The template relies on @quartz-community/types for core Quartz types.

• Branded Types: FullSlug and FilePath are used for path safety.
• vfile DataMap: Augmented with QuartzPluginData for plugin-specific metadata.
• Plugin Interfaces: QuartzTransformerPlugin, QuartzFilterPlugin, QuartzEmitterPlugin, QuartzPageTypePlugin, QuartzComponentConstructor.

Export Conventions

• Default Exports: Used for components.
• Named Exports: Used for plugin factories and types.
• Re-exports: src/index.ts re-exports all public APIs.

Dependency Management

• peerDependencies: preact, vfile, and @jackyzha0/quartz (optional).
• dependencies: @quartz-community/types, @quartz-community/utils.
• devDependencies: Build tools, linters, and test runners.

Testing Infrastructure

• vitest: Test runner.
• test helpers: Mock BuildCtx and ProcessedContent for plugin testing.

CI/CD Pipeline

• GitHub Actions: Runs npm run check on PRs and publishes to npm on version tags (v*).

Directory Structure

• src/: Source code.
  • components/: UI components.
    • scripts/: Client-side scripts (.inline.ts).
    • styles/: Component styles (.scss).
  • i18n/: Internationalization.
  • util/: Utility functions.
  • index.ts: Main entry point.
  • types.ts: Type definitions.
  • transformer.ts: Transformer implementation.
  • filter.ts: Filter implementation.
  • emitter.ts: Emitter implementation.
• dist/: Build output.
• package.json: Manifest and dependencies.
• tsup.config.ts: Build configuration.