mirror of
https://github.com/quartz-community/plugin-template.git
synced 2026-07-22 02:50:24 +00:00
74 lines
2.8 KiB
Markdown
74 lines
2.8 KiB
Markdown
|
# 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.
|