mirror of
https://github.com/jackyzha0/quartz.git
synced 2026-03-21 21:45:42 -05:00
06c8ff10f1
* Initial plan * docs: format design document for decoupling strategy Co-authored-by: saberzero1 <8161064+saberzero1@users.noreply.github.com> * feat: implement Phase 1-4 of plugin decoupling strategy - Created centralized vfile-schema.ts with all VFile data type definitions - Created plugin-context.ts with PluginUtilities abstraction layer - Created test-helpers.ts for plugin testing utilities - Made BuildCtx readonly to prevent plugin mutations - Added MutableBuildCtx for build orchestration layer - Updated components to not mutate ctx.trie - Updated FrontMatter plugin with temporary cast for backward compatibility - Updated TransformOptions to accept ReadonlyArray Co-authored-by: saberzero1 <8161064+saberzero1@users.noreply.github.com> * feat: add plugin utilities to BuildCtx and document plugin decoupling - Added utils property to BuildCtx with createPluginUtilities() - Documented plugin data dependencies with JSDoc comments on transformers and filters - Created comprehensive plugin migration guide in docs/PLUGIN_MIGRATION.md - Updated plugin types.ts with guidance on using PluginContext - All plugins now have access to ctx.utils for path, resource, and escape utilities Co-authored-by: saberzero1 <8161064+saberzero1@users.noreply.github.com> * docs: add implementation and security summaries - Created IMPLEMENTATION_SUMMARY.md documenting all phases completed - Created SECURITY_SUMMARY.md with CodeQL scan results - All security checks passed with 0 vulnerabilities - Complete documentation of changes, decisions, and impact Co-authored-by: saberzero1 <8161064+saberzero1@users.noreply.github.com> * docs: add guidance for custom plugins extending vfile data - Added section "Adding Custom VFile Fields" to PLUGIN_MIGRATION.md - Demonstrates TypeScript module augmentation for custom fields - Shows best practices for extending vfile data in third-party plugins - Clarifies that centralized schema doesn't prevent custom extensions Co-authored-by: saberzero1 <8161064+saberzero1@users.noreply.github.com> * refactor: address code review feedback - Remove `any` type annotations from component map callbacks (Breadcrumbs, FolderContent) - Fix test-helpers: change `config` to `cfg` to match BuildCtx interface - Add `trie: undefined` to mock context for completeness - Add missing vfile fields to schema: text, blocks, htmlAst, hasMermaidDiagram - Make Argv properties truly readonly with ReadonlyArgv type - Add documentation explaining module augmentation pattern is intentional - Document FrontMatter mutation as known technical debt with timeline Co-authored-by: saberzero1 <8161064+saberzero1@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: saberzero1 <8161064+saberzero1@users.noreply.github.com>
74 lines
2.4 KiB
TypeScript
74 lines
2.4 KiB
TypeScript
import { PluggableList } from "unified"
|
|
import { StaticResources } from "../util/resources"
|
|
import { ProcessedContent } from "./vfile"
|
|
import { QuartzComponent } from "../components/types"
|
|
import { FilePath } from "../util/path"
|
|
import { BuildCtx } from "../util/ctx"
|
|
import { VFile } from "vfile"
|
|
|
|
/**
|
|
* Plugin types use BuildCtx which provides readonly access to build context.
|
|
* Plugins can optionally import PluginContext from "./plugin-context" which
|
|
* extends BuildCtx with utility functions (ctx.utils).
|
|
*
|
|
* For new plugins, prefer using ctx.utils over direct imports from util/ modules.
|
|
*/
|
|
|
|
export interface PluginTypes {
|
|
transformers: QuartzTransformerPluginInstance[]
|
|
filters: QuartzFilterPluginInstance[]
|
|
emitters: QuartzEmitterPluginInstance[]
|
|
}
|
|
|
|
type OptionType = object | undefined
|
|
type ExternalResourcesFn = (ctx: BuildCtx) => Partial<StaticResources> | undefined
|
|
export type QuartzTransformerPlugin<Options extends OptionType = undefined> = (
|
|
opts?: Options,
|
|
) => QuartzTransformerPluginInstance
|
|
export type QuartzTransformerPluginInstance = {
|
|
name: string
|
|
textTransform?: (ctx: BuildCtx, src: string) => string
|
|
markdownPlugins?: (ctx: BuildCtx) => PluggableList
|
|
htmlPlugins?: (ctx: BuildCtx) => PluggableList
|
|
externalResources?: ExternalResourcesFn
|
|
}
|
|
|
|
export type QuartzFilterPlugin<Options extends OptionType = undefined> = (
|
|
opts?: Options,
|
|
) => QuartzFilterPluginInstance
|
|
export type QuartzFilterPluginInstance = {
|
|
name: string
|
|
shouldPublish(ctx: BuildCtx, content: ProcessedContent): boolean
|
|
}
|
|
|
|
export type ChangeEvent = {
|
|
type: "add" | "change" | "delete"
|
|
path: FilePath
|
|
file?: VFile
|
|
}
|
|
|
|
export type QuartzEmitterPlugin<Options extends OptionType = undefined> = (
|
|
opts?: Options,
|
|
) => QuartzEmitterPluginInstance
|
|
export type QuartzEmitterPluginInstance = {
|
|
name: string
|
|
emit: (
|
|
ctx: BuildCtx,
|
|
content: ProcessedContent[],
|
|
resources: StaticResources,
|
|
) => Promise<FilePath[]> | AsyncGenerator<FilePath>
|
|
partialEmit?: (
|
|
ctx: BuildCtx,
|
|
content: ProcessedContent[],
|
|
resources: StaticResources,
|
|
changeEvents: ChangeEvent[],
|
|
) => Promise<FilePath[]> | AsyncGenerator<FilePath> | null
|
|
/**
|
|
* Returns the components (if any) that are used in rendering the page.
|
|
* This helps Quartz optimize the page by only including necessary resources
|
|
* for components that are actually used.
|
|
*/
|
|
getQuartzComponents?: (ctx: BuildCtx) => QuartzComponent[]
|
|
externalResources?: ExternalResourcesFn
|
|
}
|