@quartz-community/types 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -229,12 +229,15 @@ interface VirtualPage {
  * Generator function: produces virtual pages from all processed content.
  * Used by page types that don't match source files but instead create
  * synthetic pages (e.g., one page per tag, one page per folder).
+ *
+ * May return a promise (Quartz 5.1+, which awaits it); declare `quartz.quartzVersion: ">=5.1.0"`
+ * when you rely on that, since older versions don't wait for it.
  */
 type PageGenerator = (args: {
     content: ProcessedContent[];
     cfg: GlobalConfiguration;
     ctx: BuildCtx;
-}) => VirtualPage[];
+}) => VirtualPage[] | Promise<VirtualPage[]>;
 /** A function that mutates a HAST tree at render time, when allFiles is available. */
 type TreeTransform = (root: Root$1, slug: FullSlug, componentData: QuartzComponentProps) => void;
 /**

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Root as HtmlRoot } from \"hast\";\nimport type { Root as MdRoot } from \"mdast\";\nimport type { Data, VFile } from \"vfile\";\nimport type { PluggableList } from \"unified\";\n\n// ============================================================================\n// Path Types - Branded string types for type-safe file paths\n// ============================================================================\n\nexport type FilePath = string & { _brand: \"FilePath\" };\nexport type FullSlug = string & { _brand: \"FullSlug\" };\nexport type SimpleSlug = string & { _brand: \"SimpleSlug\" };\n\nexport function joinSegments(...segments: string[]): FilePath {\n  return segments\n    .filter((segment) => segment.length > 0)\n    .join(\"/\")\n    .replace(/\\/+/g, \"/\") as FilePath;\n}\n\n// ============================================================================\n// Resource Types - CSS/JS resources that plugins can inject\n// ============================================================================\n\nexport type JSResource =\n  | {\n      loadTime: \"beforeDOMReady\" | \"afterDOMReady\";\n      moduleType?: \"module\";\n      spaPreserve?: boolean;\n      src: string;\n      contentType: \"external\";\n    }\n  | {\n      loadTime: \"beforeDOMReady\" | \"afterDOMReady\";\n      moduleType?: \"module\";\n      spaPreserve?: boolean;\n      script: string;\n      contentType: \"inline\";\n    };\n\nexport type CSSResource = {\n  content: string;\n  inline?: boolean;\n  spaPreserve?: boolean;\n};\n\n/**\n * A file or directory a plugin ships with the site (Quartz 5.1+), copied to\n * `<output>/static/plugins/<to>`. Client scripts get its URL from `window.quartzStaticUrl`:\n * `new URL(\"plugins/<to>/…\", window.quartzStaticUrl)`. Use it for large or optional client code\n * (loaded with `import()` only where needed) instead of inline scripts, which every page\n * downloads. Older Quartz versions ignore `assets` and leave `quartzStaticUrl` undefined.\n */\nexport interface StaticAsset {\n  /** Absolute path of a file or directory on disk (e.g. resolved from a dependency). */\n  from: string;\n  /** Destination below `static/plugins/`, e.g. \"my-plugin/vendor\". */\n  to: string;\n}\n\nexport interface StaticResources {\n  css: CSSResource[];\n  js: JSResource[];\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  additionalHead: any[];\n  /** Files copied into the site output (Quartz 5.1+). See StaticAsset. */\n  assets?: StaticAsset[];\n}\n\n// ============================================================================\n// Config Types - Quartz configuration\n// ============================================================================\n\n/**\n * Flat configuration object that components receive as `cfg` prop.\n * This matches Quartz's `GlobalConfiguration` — the resolved config\n * passed to components at render time (i.e. `ctx.cfg.configuration`).\n */\nexport interface GlobalConfiguration {\n  pageTitle?: string;\n  pageTitleSuffix?: string;\n  enableSPA?: boolean;\n  enablePopovers?: boolean;\n  analytics?: unknown;\n  ignorePatterns?: string[];\n  defaultDateType?: string;\n  baseUrl?: string;\n  theme?: unknown;\n  locale?: string;\n  /** Built-in frontmatter parsing (Quartz 5.1+). */\n  frontmatter?: BuiltinFrontmatterConfig | boolean;\n  /** Built-in link processing, formerly crawl-links (Quartz 5.1+). */\n  links?: BuiltinLinksConfig | boolean;\n  /** Built-in draft handling, formerly remove-draft (Quartz 5.1+). */\n  drafts?: BuiltinDraftsConfig | boolean;\n  /** Built-in content index / sitemap / RSS, formerly content-index (Quartz 5.1+). */\n  contentIndex?: BuiltinContentIndexConfig | boolean;\n}\n\ninterface BuiltinToggle {\n  enabled?: boolean;\n  order?: number;\n}\n\nexport interface BuiltinFrontmatterConfig extends BuiltinToggle {\n  delimiters?: string | [string, string];\n  language?: \"yaml\" | \"toml\";\n}\n\nexport interface BuiltinLinksConfig extends BuiltinToggle {\n  markdownLinkResolution?: \"absolute\" | \"relative\" | \"shortest\";\n  prettyLinks?: boolean;\n  openLinksInNewTab?: boolean;\n  lazyLoad?: boolean;\n  externalLinkIcon?: boolean;\n  disableBrokenWikilinks?: boolean;\n}\n\nexport interface BuiltinDraftsConfig extends BuiltinToggle {\n  publish?: boolean;\n}\n\nexport interface BuiltinContentIndexConfig extends BuiltinToggle {\n  enableSiteMap?: boolean;\n  enableRSS?: boolean;\n  rssLimit?: number;\n  rssFullHtml?: boolean;\n  rssSlug?: string;\n  includeEmptyFiles?: boolean;\n}\n\n/**\n * Full Quartz config with nested `configuration` property.\n * This is what `BuildCtx.cfg` holds — used in plugin hooks\n * (transformers, filters, emitters), NOT in component props.\n */\nexport interface QuartzConfig {\n  configuration: GlobalConfiguration;\n  plugins?: unknown;\n  externalPlugins?: unknown;\n}\n\n// ============================================================================\n// Context Types - Build context passed to plugin hooks\n// ============================================================================\n\nexport interface Argv {\n  directory: string;\n  verbose: boolean;\n  output: string;\n  serve: boolean;\n  watch: boolean;\n  port: number;\n  wsPort: number;\n  remoteDevHost?: string;\n  concurrency?: number;\n}\n\nexport interface BuildCtx {\n  buildId: string;\n  argv: Argv;\n  cfg: QuartzConfig;\n  allSlugs: FullSlug[];\n  allFiles: FilePath[];\n  incremental: boolean;\n  /**\n   * The site's content index (Quartz 5.1+): one entry per published page, virtual pages\n   * included. Available to emitters (except ComponentResources / PageTypeDispatcher); read-only.\n   */\n  contentIndex?: ReadonlyMap<FullSlug, Readonly<ContentDetails>>;\n}\n\n// ============================================================================\n// VFile Types - Content data types\n// ============================================================================\n\nexport type QuartzPluginData = Data;\nexport type MarkdownContent = [MdRoot, VFile];\nexport type ProcessedContent = [HtmlRoot, VFile];\n\n// ============================================================================\n// Core Component Types - The contract between Quartz and plugins\n// ============================================================================\n\nexport type QuartzComponentProps = {\n  ctx: unknown;\n  externalResources: StaticResources;\n  fileData: QuartzPluginData & Record<string, unknown>;\n  cfg: GlobalConfiguration;\n  children: unknown;\n  tree: unknown;\n  allFiles: (QuartzPluginData & Record<string, unknown>)[];\n  displayClass?: \"mobile-only\" | \"desktop-only\";\n  [key: string]: unknown;\n};\n\nexport type QuartzComponent = ((props: QuartzComponentProps) => unknown) & {\n  css?: string | string[] | undefined;\n  beforeDOMLoaded?: string | string[] | undefined;\n  afterDOMLoaded?: string | string[] | undefined;\n};\n\nexport type QuartzComponentConstructor<\n  Options extends object | undefined = undefined,\n> = (opts?: Options) => QuartzComponent;\n\nexport type StringResource = string | string[];\n\n// ============================================================================\n// Plugin Types - What Quartz expects from plugins\n// ============================================================================\n\ntype OptionType = object | undefined;\ntype ExternalResourcesFn = (\n  ctx: BuildCtx,\n) => Partial<StaticResources> | undefined;\n\nexport type { ExternalResourcesFn };\n\nexport interface PluginTypes {\n  transformers: QuartzTransformerPluginInstance[];\n  filters: QuartzFilterPluginInstance[];\n  emitters: QuartzEmitterPluginInstance[];\n  pageTypes: QuartzPageTypePluginInstance[];\n}\n\nexport type QuartzTransformerPlugin<Options extends OptionType = undefined> = (\n  opts?: Options,\n) => QuartzTransformerPluginInstance;\n\n/**\n * Optional hook on every plugin instance (Quartz 5.1+): extra JSON-serialisable fields for a page's\n * entry in `static/contentIndex.json`. Core fields cannot be overridden; on key collisions between\n * plugins the first (in plugin order) wins.\n */\nexport type ContentIndexExtension = (args: {\n  ctx: BuildCtx;\n  fileData: QuartzPluginData;\n  entry: Readonly<ContentDetails>;\n}) => Record<string, unknown> | undefined | void;\n\ninterface PluginHooks {\n  extendContentIndex?: ContentIndexExtension;\n}\n\nexport type QuartzTransformerPluginInstance = PluginHooks & {\n  name: string;\n  textTransform?: (ctx: BuildCtx, src: string) => string;\n  markdownPlugins?: (ctx: BuildCtx) => PluggableList;\n  htmlPlugins?: (ctx: BuildCtx) => PluggableList;\n  externalResources?: ExternalResourcesFn;\n};\n\nexport type QuartzFilterPlugin<Options extends OptionType = undefined> = (\n  opts?: Options,\n) => QuartzFilterPluginInstance;\n\nexport type QuartzFilterPluginInstance = PluginHooks & {\n  name: string;\n  shouldPublish(ctx: BuildCtx, content: ProcessedContent): boolean;\n};\n\nexport type ChangeEvent = {\n  type: \"add\" | \"change\" | \"delete\";\n  path: FilePath;\n  file?: VFile;\n};\n\nexport type QuartzEmitterPlugin<Options extends OptionType = undefined> = (\n  opts?: Options,\n) => QuartzEmitterPluginInstance;\n\nexport type QuartzEmitterPluginInstance = PluginHooks & {\n  name: string;\n  emit: (\n    ctx: BuildCtx,\n    content: ProcessedContent[],\n    resources: StaticResources,\n  ) => Promise<FilePath[]> | AsyncGenerator<FilePath>;\n  partialEmit?: (\n    ctx: BuildCtx,\n    content: ProcessedContent[],\n    resources: StaticResources,\n    changeEvents: ChangeEvent[],\n  ) => Promise<FilePath[]> | AsyncGenerator<FilePath> | null;\n  getQuartzComponents?: (ctx: BuildCtx) => QuartzComponent[];\n  externalResources?: ExternalResourcesFn;\n};\n\n// ============================================================================\n// PageType Plugin Types - Declarative page rendering plugins\n// ============================================================================\n\n/**\n * Matcher function: determines if a source file belongs to a page type.\n * Returns true if the page type should own this file.\n */\nexport type PageMatcher = (args: {\n  slug: FullSlug;\n  fileData: QuartzPluginData & Record<string, unknown>;\n  cfg: GlobalConfiguration;\n}) => boolean;\n\n/**\n * Virtual page descriptor for page types that generate pages\n * from aggregated data (e.g., tag indexes, folder listings).\n */\nexport interface VirtualPage {\n  slug: FullSlug;\n  title: string;\n  data: Partial<QuartzPluginData> & Record<string, unknown>;\n}\n\n/**\n * Generator function: produces virtual pages from all processed content.\n * Used by page types that don't match source files but instead create\n * synthetic pages (e.g., one page per tag, one page per folder).\n */\nexport type PageGenerator = (args: {\n  content: ProcessedContent[];\n  cfg: GlobalConfiguration;\n  ctx: BuildCtx;\n}) => VirtualPage[];\n\n/** A function that mutates a HAST tree at render time, when allFiles is available. */\nexport type TreeTransform = (\n  root: HtmlRoot,\n  slug: FullSlug,\n  componentData: QuartzComponentProps,\n) => void;\n\n/**\n * A PageType plugin definition.\n *\n * PageTypes are a declarative abstraction over page-rendering emitters.\n * Each PageType declares which files it owns (via `match`), optionally\n * generates virtual pages (via `generate`), and provides a body component\n * and layout reference for rendering.\n */\nexport type QuartzPageTypePlugin<Options extends OptionType = undefined> = (\n  opts?: Options,\n) => QuartzPageTypePluginInstance;\n\nexport type QuartzPageTypePluginInstance = PluginHooks & {\n  name: string;\n  /** Higher priority wins when multiple page types match the same file. Default: 0. */\n  priority?: number;\n  /** File extensions this page type handles (e.g. [\".canvas\"]). Files with these extensions are excluded from the default asset emitter and processed by generate() instead. */\n  fileExtensions?: string[];\n  /** Determines which source files this page type owns. */\n  match: PageMatcher;\n  /** Produces virtual pages from aggregated content data. */\n  generate?: PageGenerator;\n  /** Layout key — references a key in `layout.byPageType`. */\n  layout: string;\n  /** Optional page frame name (e.g. \"default\", \"full-width\", \"canvas\"). Defaults to \"default\". */\n  frame?: string;\n  /** The body component constructor for this page type. */\n  body: QuartzComponentConstructor;\n  /** Optional render-time HAST tree transforms (e.g. resolving inline codeblocks). */\n  treeTransforms?: (ctx: BuildCtx) => TreeTransform[];\n};\n\n// ============================================================================\n// PageFrame Types — Custom page layout frames\n// ============================================================================\n\n/**\n * Props passed to a PageFrame's render function.\n * Contains the resolved layout components and the shared component data.\n */\nexport interface PageFrameProps {\n  /** Component data shared across all components on the page */\n  componentData: QuartzComponentProps;\n  /** The Head component (rendered in <head>) — NOT used by frames, included for completeness */\n  head: QuartzComponent;\n  /** Header slot components (rendered inside <header>) */\n  header: QuartzComponent[];\n  /** Components rendered before the page body */\n  beforeBody: QuartzComponent[];\n  /** The page body component (Content) */\n  pageBody: QuartzComponent;\n  /** Components rendered after the page body */\n  afterBody: QuartzComponent[];\n  /** Left sidebar components */\n  left: QuartzComponent[];\n  /** Right sidebar components */\n  right: QuartzComponent[];\n  /** Footer components */\n  footer: QuartzComponent[];\n  /**\n   * Sidebar modes from `layout.sidebars` (Quartz 5.1+; undefined before). Frames with sidebars\n   * should put them on the sidebar elements as `data-sidebar-mode`; Quartz's stylesheet does the rest.\n   */\n  sidebars?: { left: SidebarMode; right: SidebarMode };\n}\n\n/**\n * How a sidebar handles content taller than the screen (`layout.sidebars`, Quartz 5.1+):\n * `fit` (default) — one screen tall, components shrink and scroll; `scroll` — stays in view and\n * scrolls itself; `static` — scrolls away with the page.\n */\nexport type SidebarMode = \"fit\" | \"scroll\" | \"static\";\n\n/**\n * A PageFrame defines the inner HTML structure of a page inside the\n * `<div id=\"quartz-root\">` shell. Different frames can produce completely\n * different layouts (e.g. with/without sidebars, horizontal scroll, etc.)\n * while the outer shell (html, head, body, quartz-root) remains stable\n * for SPA navigation.\n *\n * The `render` function returns `unknown` to avoid coupling to a specific\n * JSX runtime (Preact, React, etc.). Quartz core casts this to JSX.Element.\n */\nexport interface PageFrame {\n  /** Unique name for this frame (e.g. \"default\", \"full-width\", \"canvas\") */\n  name: string;\n  /** Render the inner page structure. Returns a JSX tree to be placed inside Body > #quartz-body. */\n  render: (props: PageFrameProps) => unknown;\n  /** Optional CSS string to include when this frame is active */\n  css?: string;\n}\n\nexport type HTMLAttributes = Record<\n  string,\n  string | number | boolean | undefined\n>;\n\nexport type EventHandler = (event: Event) => void;\n\nexport type CleanupFunction = () => void;\n\nexport type ClassValue =\n  string | number | boolean | undefined | null | ClassValue[];\n\n// ============================================================================\n// Content Index Types - Data shape for contentIndex.json\n// ============================================================================\n\nexport type ContentDetails = {\n  slug: FullSlug;\n  filePath: FilePath;\n  title: string;\n  links: string[];\n  tags: string[];\n  content: string;\n  richContent?: string;\n  date?: Date;\n  description?: string;\n  /** Fields added by plugins through `extendContentIndex` (Quartz 5.1+). */\n  [extra: string]: unknown;\n};\n\nexport type ContentIndex = Record<FullSlug, ContentDetails>;\n\n// ============================================================================\n// Sort & Theme Types\n// ============================================================================\n\nexport type SortFn = (f1: QuartzPluginData, f2: QuartzPluginData) => number;\n\nexport type ThemeKey = \"lightMode\" | \"darkMode\";\n\nexport type ValidDateType = \"created\" | \"modified\" | \"published\";\n\n// ============================================================================\n// VFile DataMap Augmentation — canonical vfile shape for Quartz\n// ============================================================================\n\ndeclare module \"vfile\" {\n  interface DataMap {\n    slug: FullSlug;\n    filePath: FilePath;\n    relativePath: FilePath;\n    description: string;\n    text: string;\n    links: SimpleSlug[];\n    toc: { depth: number; text: string; slug: string }[];\n    collapseToc: boolean;\n    blocks: Record<string, import(\"hast\").Element>;\n    htmlAst: import(\"hast\").Root;\n    hasMermaidDiagram: boolean | undefined;\n    frontmatter: { [key: string]: unknown } & {\n      title: string;\n    } & Partial<{\n        tags: string[];\n        aliases: string[];\n        modified: string;\n        created: string;\n        published: string;\n        description: string;\n        socialDescription: string;\n        publish: boolean | string;\n        draft: boolean | string;\n        lang: string;\n        enableToc: string;\n        cssclasses: string[];\n        socialImage: string;\n        comments: boolean | string;\n      }>;\n    dates: {\n      created: Date;\n      modified: Date;\n      published: Date;\n    };\n    defaultDateType?: ValidDateType;\n  }\n}\n"],"mappings":";AAaO,SAAS,gBAAgB,UAA8B;AAC5D,SAAO,SACJ,OAAO,CAAC,YAAY,QAAQ,SAAS,CAAC,EACtC,KAAK,GAAG,EACR,QAAQ,QAAQ,GAAG;AACxB;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Root as HtmlRoot } from \"hast\";\nimport type { Root as MdRoot } from \"mdast\";\nimport type { Data, VFile } from \"vfile\";\nimport type { PluggableList } from \"unified\";\n\n// ============================================================================\n// Path Types - Branded string types for type-safe file paths\n// ============================================================================\n\nexport type FilePath = string & { _brand: \"FilePath\" };\nexport type FullSlug = string & { _brand: \"FullSlug\" };\nexport type SimpleSlug = string & { _brand: \"SimpleSlug\" };\n\nexport function joinSegments(...segments: string[]): FilePath {\n  return segments\n    .filter((segment) => segment.length > 0)\n    .join(\"/\")\n    .replace(/\\/+/g, \"/\") as FilePath;\n}\n\n// ============================================================================\n// Resource Types - CSS/JS resources that plugins can inject\n// ============================================================================\n\nexport type JSResource =\n  | {\n      loadTime: \"beforeDOMReady\" | \"afterDOMReady\";\n      moduleType?: \"module\";\n      spaPreserve?: boolean;\n      src: string;\n      contentType: \"external\";\n    }\n  | {\n      loadTime: \"beforeDOMReady\" | \"afterDOMReady\";\n      moduleType?: \"module\";\n      spaPreserve?: boolean;\n      script: string;\n      contentType: \"inline\";\n    };\n\nexport type CSSResource = {\n  content: string;\n  inline?: boolean;\n  spaPreserve?: boolean;\n};\n\n/**\n * A file or directory a plugin ships with the site (Quartz 5.1+), copied to\n * `<output>/static/plugins/<to>`. Client scripts get its URL from `window.quartzStaticUrl`:\n * `new URL(\"plugins/<to>/…\", window.quartzStaticUrl)`. Use it for large or optional client code\n * (loaded with `import()` only where needed) instead of inline scripts, which every page\n * downloads. Older Quartz versions ignore `assets` and leave `quartzStaticUrl` undefined.\n */\nexport interface StaticAsset {\n  /** Absolute path of a file or directory on disk (e.g. resolved from a dependency). */\n  from: string;\n  /** Destination below `static/plugins/`, e.g. \"my-plugin/vendor\". */\n  to: string;\n}\n\nexport interface StaticResources {\n  css: CSSResource[];\n  js: JSResource[];\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  additionalHead: any[];\n  /** Files copied into the site output (Quartz 5.1+). See StaticAsset. */\n  assets?: StaticAsset[];\n}\n\n// ============================================================================\n// Config Types - Quartz configuration\n// ============================================================================\n\n/**\n * Flat configuration object that components receive as `cfg` prop.\n * This matches Quartz's `GlobalConfiguration` — the resolved config\n * passed to components at render time (i.e. `ctx.cfg.configuration`).\n */\nexport interface GlobalConfiguration {\n  pageTitle?: string;\n  pageTitleSuffix?: string;\n  enableSPA?: boolean;\n  enablePopovers?: boolean;\n  analytics?: unknown;\n  ignorePatterns?: string[];\n  defaultDateType?: string;\n  baseUrl?: string;\n  theme?: unknown;\n  locale?: string;\n  /** Built-in frontmatter parsing (Quartz 5.1+). */\n  frontmatter?: BuiltinFrontmatterConfig | boolean;\n  /** Built-in link processing, formerly crawl-links (Quartz 5.1+). */\n  links?: BuiltinLinksConfig | boolean;\n  /** Built-in draft handling, formerly remove-draft (Quartz 5.1+). */\n  drafts?: BuiltinDraftsConfig | boolean;\n  /** Built-in content index / sitemap / RSS, formerly content-index (Quartz 5.1+). */\n  contentIndex?: BuiltinContentIndexConfig | boolean;\n}\n\ninterface BuiltinToggle {\n  enabled?: boolean;\n  order?: number;\n}\n\nexport interface BuiltinFrontmatterConfig extends BuiltinToggle {\n  delimiters?: string | [string, string];\n  language?: \"yaml\" | \"toml\";\n}\n\nexport interface BuiltinLinksConfig extends BuiltinToggle {\n  markdownLinkResolution?: \"absolute\" | \"relative\" | \"shortest\";\n  prettyLinks?: boolean;\n  openLinksInNewTab?: boolean;\n  lazyLoad?: boolean;\n  externalLinkIcon?: boolean;\n  disableBrokenWikilinks?: boolean;\n}\n\nexport interface BuiltinDraftsConfig extends BuiltinToggle {\n  publish?: boolean;\n}\n\nexport interface BuiltinContentIndexConfig extends BuiltinToggle {\n  enableSiteMap?: boolean;\n  enableRSS?: boolean;\n  rssLimit?: number;\n  rssFullHtml?: boolean;\n  rssSlug?: string;\n  includeEmptyFiles?: boolean;\n}\n\n/**\n * Full Quartz config with nested `configuration` property.\n * This is what `BuildCtx.cfg` holds — used in plugin hooks\n * (transformers, filters, emitters), NOT in component props.\n */\nexport interface QuartzConfig {\n  configuration: GlobalConfiguration;\n  plugins?: unknown;\n  externalPlugins?: unknown;\n}\n\n// ============================================================================\n// Context Types - Build context passed to plugin hooks\n// ============================================================================\n\nexport interface Argv {\n  directory: string;\n  verbose: boolean;\n  output: string;\n  serve: boolean;\n  watch: boolean;\n  port: number;\n  wsPort: number;\n  remoteDevHost?: string;\n  concurrency?: number;\n}\n\nexport interface BuildCtx {\n  buildId: string;\n  argv: Argv;\n  cfg: QuartzConfig;\n  allSlugs: FullSlug[];\n  allFiles: FilePath[];\n  incremental: boolean;\n  /**\n   * The site's content index (Quartz 5.1+): one entry per published page, virtual pages\n   * included. Available to emitters (except ComponentResources / PageTypeDispatcher); read-only.\n   */\n  contentIndex?: ReadonlyMap<FullSlug, Readonly<ContentDetails>>;\n}\n\n// ============================================================================\n// VFile Types - Content data types\n// ============================================================================\n\nexport type QuartzPluginData = Data;\nexport type MarkdownContent = [MdRoot, VFile];\nexport type ProcessedContent = [HtmlRoot, VFile];\n\n// ============================================================================\n// Core Component Types - The contract between Quartz and plugins\n// ============================================================================\n\nexport type QuartzComponentProps = {\n  ctx: unknown;\n  externalResources: StaticResources;\n  fileData: QuartzPluginData & Record<string, unknown>;\n  cfg: GlobalConfiguration;\n  children: unknown;\n  tree: unknown;\n  allFiles: (QuartzPluginData & Record<string, unknown>)[];\n  displayClass?: \"mobile-only\" | \"desktop-only\";\n  [key: string]: unknown;\n};\n\nexport type QuartzComponent = ((props: QuartzComponentProps) => unknown) & {\n  css?: string | string[] | undefined;\n  beforeDOMLoaded?: string | string[] | undefined;\n  afterDOMLoaded?: string | string[] | undefined;\n};\n\nexport type QuartzComponentConstructor<\n  Options extends object | undefined = undefined,\n> = (opts?: Options) => QuartzComponent;\n\nexport type StringResource = string | string[];\n\n// ============================================================================\n// Plugin Types - What Quartz expects from plugins\n// ============================================================================\n\ntype OptionType = object | undefined;\ntype ExternalResourcesFn = (\n  ctx: BuildCtx,\n) => Partial<StaticResources> | undefined;\n\nexport type { ExternalResourcesFn };\n\nexport interface PluginTypes {\n  transformers: QuartzTransformerPluginInstance[];\n  filters: QuartzFilterPluginInstance[];\n  emitters: QuartzEmitterPluginInstance[];\n  pageTypes: QuartzPageTypePluginInstance[];\n}\n\nexport type QuartzTransformerPlugin<Options extends OptionType = undefined> = (\n  opts?: Options,\n) => QuartzTransformerPluginInstance;\n\n/**\n * Optional hook on every plugin instance (Quartz 5.1+): extra JSON-serialisable fields for a page's\n * entry in `static/contentIndex.json`. Core fields cannot be overridden; on key collisions between\n * plugins the first (in plugin order) wins.\n */\nexport type ContentIndexExtension = (args: {\n  ctx: BuildCtx;\n  fileData: QuartzPluginData;\n  entry: Readonly<ContentDetails>;\n}) => Record<string, unknown> | undefined | void;\n\ninterface PluginHooks {\n  extendContentIndex?: ContentIndexExtension;\n}\n\nexport type QuartzTransformerPluginInstance = PluginHooks & {\n  name: string;\n  textTransform?: (ctx: BuildCtx, src: string) => string;\n  markdownPlugins?: (ctx: BuildCtx) => PluggableList;\n  htmlPlugins?: (ctx: BuildCtx) => PluggableList;\n  externalResources?: ExternalResourcesFn;\n};\n\nexport type QuartzFilterPlugin<Options extends OptionType = undefined> = (\n  opts?: Options,\n) => QuartzFilterPluginInstance;\n\nexport type QuartzFilterPluginInstance = PluginHooks & {\n  name: string;\n  shouldPublish(ctx: BuildCtx, content: ProcessedContent): boolean;\n};\n\nexport type ChangeEvent = {\n  type: \"add\" | \"change\" | \"delete\";\n  path: FilePath;\n  file?: VFile;\n};\n\nexport type QuartzEmitterPlugin<Options extends OptionType = undefined> = (\n  opts?: Options,\n) => QuartzEmitterPluginInstance;\n\nexport type QuartzEmitterPluginInstance = PluginHooks & {\n  name: string;\n  emit: (\n    ctx: BuildCtx,\n    content: ProcessedContent[],\n    resources: StaticResources,\n  ) => Promise<FilePath[]> | AsyncGenerator<FilePath>;\n  partialEmit?: (\n    ctx: BuildCtx,\n    content: ProcessedContent[],\n    resources: StaticResources,\n    changeEvents: ChangeEvent[],\n  ) => Promise<FilePath[]> | AsyncGenerator<FilePath> | null;\n  getQuartzComponents?: (ctx: BuildCtx) => QuartzComponent[];\n  externalResources?: ExternalResourcesFn;\n};\n\n// ============================================================================\n// PageType Plugin Types - Declarative page rendering plugins\n// ============================================================================\n\n/**\n * Matcher function: determines if a source file belongs to a page type.\n * Returns true if the page type should own this file.\n */\nexport type PageMatcher = (args: {\n  slug: FullSlug;\n  fileData: QuartzPluginData & Record<string, unknown>;\n  cfg: GlobalConfiguration;\n}) => boolean;\n\n/**\n * Virtual page descriptor for page types that generate pages\n * from aggregated data (e.g., tag indexes, folder listings).\n */\nexport interface VirtualPage {\n  slug: FullSlug;\n  title: string;\n  data: Partial<QuartzPluginData> & Record<string, unknown>;\n}\n\n/**\n * Generator function: produces virtual pages from all processed content.\n * Used by page types that don't match source files but instead create\n * synthetic pages (e.g., one page per tag, one page per folder).\n *\n * May return a promise (Quartz 5.1+, which awaits it); declare `quartz.quartzVersion: \">=5.1.0\"`\n * when you rely on that, since older versions don't wait for it.\n */\nexport type PageGenerator = (args: {\n  content: ProcessedContent[];\n  cfg: GlobalConfiguration;\n  ctx: BuildCtx;\n}) => VirtualPage[] | Promise<VirtualPage[]>;\n\n/** A function that mutates a HAST tree at render time, when allFiles is available. */\nexport type TreeTransform = (\n  root: HtmlRoot,\n  slug: FullSlug,\n  componentData: QuartzComponentProps,\n) => void;\n\n/**\n * A PageType plugin definition.\n *\n * PageTypes are a declarative abstraction over page-rendering emitters.\n * Each PageType declares which files it owns (via `match`), optionally\n * generates virtual pages (via `generate`), and provides a body component\n * and layout reference for rendering.\n */\nexport type QuartzPageTypePlugin<Options extends OptionType = undefined> = (\n  opts?: Options,\n) => QuartzPageTypePluginInstance;\n\nexport type QuartzPageTypePluginInstance = PluginHooks & {\n  name: string;\n  /** Higher priority wins when multiple page types match the same file. Default: 0. */\n  priority?: number;\n  /** File extensions this page type handles (e.g. [\".canvas\"]). Files with these extensions are excluded from the default asset emitter and processed by generate() instead. */\n  fileExtensions?: string[];\n  /** Determines which source files this page type owns. */\n  match: PageMatcher;\n  /** Produces virtual pages from aggregated content data. */\n  generate?: PageGenerator;\n  /** Layout key — references a key in `layout.byPageType`. */\n  layout: string;\n  /** Optional page frame name (e.g. \"default\", \"full-width\", \"canvas\"). Defaults to \"default\". */\n  frame?: string;\n  /** The body component constructor for this page type. */\n  body: QuartzComponentConstructor;\n  /** Optional render-time HAST tree transforms (e.g. resolving inline codeblocks). */\n  treeTransforms?: (ctx: BuildCtx) => TreeTransform[];\n};\n\n// ============================================================================\n// PageFrame Types — Custom page layout frames\n// ============================================================================\n\n/**\n * Props passed to a PageFrame's render function.\n * Contains the resolved layout components and the shared component data.\n */\nexport interface PageFrameProps {\n  /** Component data shared across all components on the page */\n  componentData: QuartzComponentProps;\n  /** The Head component (rendered in <head>) — NOT used by frames, included for completeness */\n  head: QuartzComponent;\n  /** Header slot components (rendered inside <header>) */\n  header: QuartzComponent[];\n  /** Components rendered before the page body */\n  beforeBody: QuartzComponent[];\n  /** The page body component (Content) */\n  pageBody: QuartzComponent;\n  /** Components rendered after the page body */\n  afterBody: QuartzComponent[];\n  /** Left sidebar components */\n  left: QuartzComponent[];\n  /** Right sidebar components */\n  right: QuartzComponent[];\n  /** Footer components */\n  footer: QuartzComponent[];\n  /**\n   * Sidebar modes from `layout.sidebars` (Quartz 5.1+; undefined before). Frames with sidebars\n   * should put them on the sidebar elements as `data-sidebar-mode`; Quartz's stylesheet does the rest.\n   */\n  sidebars?: { left: SidebarMode; right: SidebarMode };\n}\n\n/**\n * How a sidebar handles content taller than the screen (`layout.sidebars`, Quartz 5.1+):\n * `fit` (default) — one screen tall, components shrink and scroll; `scroll` — stays in view and\n * scrolls itself; `static` — scrolls away with the page.\n */\nexport type SidebarMode = \"fit\" | \"scroll\" | \"static\";\n\n/**\n * A PageFrame defines the inner HTML structure of a page inside the\n * `<div id=\"quartz-root\">` shell. Different frames can produce completely\n * different layouts (e.g. with/without sidebars, horizontal scroll, etc.)\n * while the outer shell (html, head, body, quartz-root) remains stable\n * for SPA navigation.\n *\n * The `render` function returns `unknown` to avoid coupling to a specific\n * JSX runtime (Preact, React, etc.). Quartz core casts this to JSX.Element.\n */\nexport interface PageFrame {\n  /** Unique name for this frame (e.g. \"default\", \"full-width\", \"canvas\") */\n  name: string;\n  /** Render the inner page structure. Returns a JSX tree to be placed inside Body > #quartz-body. */\n  render: (props: PageFrameProps) => unknown;\n  /** Optional CSS string to include when this frame is active */\n  css?: string;\n}\n\nexport type HTMLAttributes = Record<\n  string,\n  string | number | boolean | undefined\n>;\n\nexport type EventHandler = (event: Event) => void;\n\nexport type CleanupFunction = () => void;\n\nexport type ClassValue =\n  string | number | boolean | undefined | null | ClassValue[];\n\n// ============================================================================\n// Content Index Types - Data shape for contentIndex.json\n// ============================================================================\n\nexport type ContentDetails = {\n  slug: FullSlug;\n  filePath: FilePath;\n  title: string;\n  links: string[];\n  tags: string[];\n  content: string;\n  richContent?: string;\n  date?: Date;\n  description?: string;\n  /** Fields added by plugins through `extendContentIndex` (Quartz 5.1+). */\n  [extra: string]: unknown;\n};\n\nexport type ContentIndex = Record<FullSlug, ContentDetails>;\n\n// ============================================================================\n// Sort & Theme Types\n// ============================================================================\n\nexport type SortFn = (f1: QuartzPluginData, f2: QuartzPluginData) => number;\n\nexport type ThemeKey = \"lightMode\" | \"darkMode\";\n\nexport type ValidDateType = \"created\" | \"modified\" | \"published\";\n\n// ============================================================================\n// VFile DataMap Augmentation — canonical vfile shape for Quartz\n// ============================================================================\n\ndeclare module \"vfile\" {\n  interface DataMap {\n    slug: FullSlug;\n    filePath: FilePath;\n    relativePath: FilePath;\n    description: string;\n    text: string;\n    links: SimpleSlug[];\n    toc: { depth: number; text: string; slug: string }[];\n    collapseToc: boolean;\n    blocks: Record<string, import(\"hast\").Element>;\n    htmlAst: import(\"hast\").Root;\n    hasMermaidDiagram: boolean | undefined;\n    frontmatter: { [key: string]: unknown } & {\n      title: string;\n    } & Partial<{\n        tags: string[];\n        aliases: string[];\n        modified: string;\n        created: string;\n        published: string;\n        description: string;\n        socialDescription: string;\n        publish: boolean | string;\n        draft: boolean | string;\n        lang: string;\n        enableToc: string;\n        cssclasses: string[];\n        socialImage: string;\n        comments: boolean | string;\n      }>;\n    dates: {\n      created: Date;\n      modified: Date;\n      published: Date;\n    };\n    defaultDateType?: ValidDateType;\n  }\n}\n"],"mappings":";AAaO,SAAS,gBAAgB,UAA8B;AAC5D,SAAO,SACJ,OAAO,CAAC,YAAY,QAAQ,SAAS,CAAC,EACtC,KAAK,GAAG,EACR,QAAQ,QAAQ,GAAG;AACxB;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quartz-community/types",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Type definitions for Quartz community plugins",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -315,12 +315,15 @@ export interface VirtualPage {
  * Generator function: produces virtual pages from all processed content.
  * Used by page types that don't match source files but instead create
  * synthetic pages (e.g., one page per tag, one page per folder).
+ *
+ * May return a promise (Quartz 5.1+, which awaits it); declare `quartz.quartzVersion: ">=5.1.0"`
+ * when you rely on that, since older versions don't wait for it.
  */
 export type PageGenerator = (args: {
   content: ProcessedContent[];
   cfg: GlobalConfiguration;
   ctx: BuildCtx;
-}) => VirtualPage[];
+}) => VirtualPage[] | Promise<VirtualPage[]>;
 
 /** A function that mutates a HAST tree at render time, when allFiles is available. */
 export type TreeTransform = (