@quartz-community/types 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -32,10 +32,25 @@ type CSSResource = {
     inline?: boolean;
     spaPreserve?: boolean;
 };
+/**
+ * A file or directory a plugin ships with the site (Quartz 5.1+), copied to
+ * `<output>/static/plugins/<to>`. Client scripts get its URL from `window.quartzStaticUrl`:
+ * `new URL("plugins/<to>/…", window.quartzStaticUrl)`. Use it for large or optional client code
+ * (loaded with `import()` only where needed) instead of inline scripts, which every page
+ * downloads. Older Quartz versions ignore `assets` and leave `quartzStaticUrl` undefined.
+ */
+interface StaticAsset {
+    /** Absolute path of a file or directory on disk (e.g. resolved from a dependency). */
+    from: string;
+    /** Destination below `static/plugins/`, e.g. "my-plugin/vendor". */
+    to: string;
+}
 interface StaticResources {
     css: CSSResource[];
     js: JSResource[];
     additionalHead: any[];
+    /** Files copied into the site output (Quartz 5.1+). See StaticAsset. */
+    assets?: StaticAsset[];
 }
 /**
  * Flat configuration object that components receive as `cfg` prop.
@@ -53,6 +68,41 @@ interface GlobalConfiguration {
     baseUrl?: string;
     theme?: unknown;
     locale?: string;
+    /** Built-in frontmatter parsing (Quartz 5.1+). */
+    frontmatter?: BuiltinFrontmatterConfig | boolean;
+    /** Built-in link processing, formerly crawl-links (Quartz 5.1+). */
+    links?: BuiltinLinksConfig | boolean;
+    /** Built-in draft handling, formerly remove-draft (Quartz 5.1+). */
+    drafts?: BuiltinDraftsConfig | boolean;
+    /** Built-in content index / sitemap / RSS, formerly content-index (Quartz 5.1+). */
+    contentIndex?: BuiltinContentIndexConfig | boolean;
+}
+interface BuiltinToggle {
+    enabled?: boolean;
+    order?: number;
+}
+interface BuiltinFrontmatterConfig extends BuiltinToggle {
+    delimiters?: string | [string, string];
+    language?: "yaml" | "toml";
+}
+interface BuiltinLinksConfig extends BuiltinToggle {
+    markdownLinkResolution?: "absolute" | "relative" | "shortest";
+    prettyLinks?: boolean;
+    openLinksInNewTab?: boolean;
+    lazyLoad?: boolean;
+    externalLinkIcon?: boolean;
+    disableBrokenWikilinks?: boolean;
+}
+interface BuiltinDraftsConfig extends BuiltinToggle {
+    publish?: boolean;
+}
+interface BuiltinContentIndexConfig extends BuiltinToggle {
+    enableSiteMap?: boolean;
+    enableRSS?: boolean;
+    rssLimit?: number;
+    rssFullHtml?: boolean;
+    rssSlug?: string;
+    includeEmptyFiles?: boolean;
 }
 /**
  * Full Quartz config with nested `configuration` property.
@@ -82,6 +132,11 @@ interface BuildCtx {
     allSlugs: FullSlug[];
     allFiles: FilePath[];
     incremental: boolean;
+    /**
+     * The site's content index (Quartz 5.1+): one entry per published page, virtual pages
+     * included. Available to emitters (except ComponentResources / PageTypeDispatcher); read-only.
+     */
+    contentIndex?: ReadonlyMap<FullSlug, Readonly<ContentDetails>>;
 }
 type QuartzPluginData = Data;
 type MarkdownContent = [Root, VFile];
@@ -114,7 +169,20 @@ interface PluginTypes {
     pageTypes: QuartzPageTypePluginInstance[];
 }
 type QuartzTransformerPlugin<Options extends OptionType = undefined> = (opts?: Options) => QuartzTransformerPluginInstance;
-type QuartzTransformerPluginInstance = {
+/**
+ * Optional hook on every plugin instance (Quartz 5.1+): extra JSON-serialisable fields for a page's
+ * entry in `static/contentIndex.json`. Core fields cannot be overridden; on key collisions between
+ * plugins the first (in plugin order) wins.
+ */
+type ContentIndexExtension = (args: {
+    ctx: BuildCtx;
+    fileData: QuartzPluginData;
+    entry: Readonly<ContentDetails>;
+}) => Record<string, unknown> | undefined | void;
+interface PluginHooks {
+    extendContentIndex?: ContentIndexExtension;
+}
+type QuartzTransformerPluginInstance = PluginHooks & {
     name: string;
     textTransform?: (ctx: BuildCtx, src: string) => string;
     markdownPlugins?: (ctx: BuildCtx) => PluggableList;
@@ -122,7 +190,7 @@ type QuartzTransformerPluginInstance = {
     externalResources?: ExternalResourcesFn;
 };
 type QuartzFilterPlugin<Options extends OptionType = undefined> = (opts?: Options) => QuartzFilterPluginInstance;
-type QuartzFilterPluginInstance = {
+type QuartzFilterPluginInstance = PluginHooks & {
     name: string;
     shouldPublish(ctx: BuildCtx, content: ProcessedContent): boolean;
 };
@@ -132,7 +200,7 @@ type ChangeEvent = {
     file?: VFile;
 };
 type QuartzEmitterPlugin<Options extends OptionType = undefined> = (opts?: Options) => QuartzEmitterPluginInstance;
-type QuartzEmitterPluginInstance = {
+type QuartzEmitterPluginInstance = PluginHooks & {
     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;
@@ -161,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;
 /**
@@ -178,7 +249,7 @@ type TreeTransform = (root: Root$1, slug: FullSlug, componentData: QuartzCompone
  * and layout reference for rendering.
  */
 type QuartzPageTypePlugin<Options extends OptionType = undefined> = (opts?: Options) => QuartzPageTypePluginInstance;
-type QuartzPageTypePluginInstance = {
+type QuartzPageTypePluginInstance = PluginHooks & {
     name: string;
     /** Higher priority wins when multiple page types match the same file. Default: 0. */
     priority?: number;
@@ -220,7 +291,21 @@ interface PageFrameProps {
     right: QuartzComponent[];
     /** Footer components */
     footer: QuartzComponent[];
+    /**
+     * Sidebar modes from `layout.sidebars` (Quartz 5.1+; undefined before). Frames with sidebars
+     * should put them on the sidebar elements as `data-sidebar-mode`; Quartz's stylesheet does the rest.
+     */
+    sidebars?: {
+        left: SidebarMode;
+        right: SidebarMode;
+    };
 }
+/**
+ * How a sidebar handles content taller than the screen (`layout.sidebars`, Quartz 5.1+):
+ * `fit` (default) — one screen tall, components shrink and scroll; `scroll` — stays in view and
+ * scrolls itself; `static` — scrolls away with the page.
+ */
+type SidebarMode = "fit" | "scroll" | "static";
 /**
  * A PageFrame defines the inner HTML structure of a page inside the
  * `<div id="quartz-root">` shell. Different frames can produce completely
@@ -253,6 +338,8 @@ type ContentDetails = {
     richContent?: string;
     date?: Date;
     description?: string;
+    /** Fields added by plugins through `extendContentIndex` (Quartz 5.1+). */
+    [extra: string]: unknown;
 };
 type ContentIndex = Record<FullSlug, ContentDetails>;
 type SortFn = (f1: QuartzPluginData, f2: QuartzPluginData) => number;
@@ -304,4 +391,4 @@ declare module "vfile" {
     }
 }
 
-export { type Argv, type BuildCtx, type CSSResource, type ChangeEvent, type ClassValue, type CleanupFunction, type ContentDetails, type ContentIndex, type EventHandler, type ExternalResourcesFn, type FilePath, type FullSlug, type GlobalConfiguration, type HTMLAttributes, type JSResource, type MarkdownContent, type PageFrame, type PageFrameProps, type PageGenerator, type PageMatcher, type PluginTypes, type ProcessedContent, type QuartzComponent, type QuartzComponentConstructor, type QuartzComponentProps, type QuartzConfig, type QuartzEmitterPlugin, type QuartzEmitterPluginInstance, type QuartzFilterPlugin, type QuartzFilterPluginInstance, type QuartzPageTypePlugin, type QuartzPageTypePluginInstance, type QuartzPluginData, type QuartzTransformerPlugin, type QuartzTransformerPluginInstance, type SimpleSlug, type SortFn, type StaticResources, type StringResource, type ThemeKey, type TreeTransform, type ValidDateType, type VirtualPage, joinSegments };
+export { type Argv, type BuildCtx, type BuiltinContentIndexConfig, type BuiltinDraftsConfig, type BuiltinFrontmatterConfig, type BuiltinLinksConfig, type CSSResource, type ChangeEvent, type ClassValue, type CleanupFunction, type ContentDetails, type ContentIndex, type ContentIndexExtension, type EventHandler, type ExternalResourcesFn, type FilePath, type FullSlug, type GlobalConfiguration, type HTMLAttributes, type JSResource, type MarkdownContent, type PageFrame, type PageFrameProps, type PageGenerator, type PageMatcher, type PluginTypes, type ProcessedContent, type QuartzComponent, type QuartzComponentConstructor, type QuartzComponentProps, type QuartzConfig, type QuartzEmitterPlugin, type QuartzEmitterPluginInstance, type QuartzFilterPlugin, type QuartzFilterPluginInstance, type QuartzPageTypePlugin, type QuartzPageTypePluginInstance, type QuartzPluginData, type QuartzTransformerPlugin, type QuartzTransformerPluginInstance, type SidebarMode, type SimpleSlug, type SortFn, type StaticAsset, type StaticResources, type StringResource, type ThemeKey, type TreeTransform, type ValidDateType, type VirtualPage, joinSegments };

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\nexport interface StaticResources {\n  css: CSSResource[];\n  js: JSResource[];\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  additionalHead: any[];\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}\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\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\nexport type QuartzTransformerPluginInstance = {\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 = {\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 = {\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 = {\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\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\n  | number\n  | boolean\n  | undefined\n  | null\n  | 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};\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.0.0",
+  "version": "1.2.0",
   "description": "Type definitions for Quartz community plugins",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,8 @@
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build",
-    "release": "npm run build && changeset publish"
+    "release": "npm run build && changeset publish",
+    "version-packages": "changeset version && npm install --package-lock-only --ignore-scripts --no-audit --no-fund"
   },
   "dependencies": {
     "unified": "^11.0.5",

package/src/index.ts

@@ -44,11 +44,27 @@ export type CSSResource = {
   spaPreserve?: boolean;
 };
 
+/**
+ * A file or directory a plugin ships with the site (Quartz 5.1+), copied to
+ * `<output>/static/plugins/<to>`. Client scripts get its URL from `window.quartzStaticUrl`:
+ * `new URL("plugins/<to>/…", window.quartzStaticUrl)`. Use it for large or optional client code
+ * (loaded with `import()` only where needed) instead of inline scripts, which every page
+ * downloads. Older Quartz versions ignore `assets` and leave `quartzStaticUrl` undefined.
+ */
+export interface StaticAsset {
+  /** Absolute path of a file or directory on disk (e.g. resolved from a dependency). */
+  from: string;
+  /** Destination below `static/plugins/`, e.g. "my-plugin/vendor". */
+  to: string;
+}
+
 export interface StaticResources {
   css: CSSResource[];
   js: JSResource[];
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   additionalHead: any[];
+  /** Files copied into the site output (Quartz 5.1+). See StaticAsset. */
+  assets?: StaticAsset[];
 }
 
 // ============================================================================
@@ -71,6 +87,46 @@ export interface GlobalConfiguration {
   baseUrl?: string;
   theme?: unknown;
   locale?: string;
+  /** Built-in frontmatter parsing (Quartz 5.1+). */
+  frontmatter?: BuiltinFrontmatterConfig | boolean;
+  /** Built-in link processing, formerly crawl-links (Quartz 5.1+). */
+  links?: BuiltinLinksConfig | boolean;
+  /** Built-in draft handling, formerly remove-draft (Quartz 5.1+). */
+  drafts?: BuiltinDraftsConfig | boolean;
+  /** Built-in content index / sitemap / RSS, formerly content-index (Quartz 5.1+). */
+  contentIndex?: BuiltinContentIndexConfig | boolean;
+}
+
+interface BuiltinToggle {
+  enabled?: boolean;
+  order?: number;
+}
+
+export interface BuiltinFrontmatterConfig extends BuiltinToggle {
+  delimiters?: string | [string, string];
+  language?: "yaml" | "toml";
+}
+
+export interface BuiltinLinksConfig extends BuiltinToggle {
+  markdownLinkResolution?: "absolute" | "relative" | "shortest";
+  prettyLinks?: boolean;
+  openLinksInNewTab?: boolean;
+  lazyLoad?: boolean;
+  externalLinkIcon?: boolean;
+  disableBrokenWikilinks?: boolean;
+}
+
+export interface BuiltinDraftsConfig extends BuiltinToggle {
+  publish?: boolean;
+}
+
+export interface BuiltinContentIndexConfig extends BuiltinToggle {
+  enableSiteMap?: boolean;
+  enableRSS?: boolean;
+  rssLimit?: number;
+  rssFullHtml?: boolean;
+  rssSlug?: string;
+  includeEmptyFiles?: boolean;
 }
 
 /**
@@ -107,6 +163,11 @@ export interface BuildCtx {
   allSlugs: FullSlug[];
   allFiles: FilePath[];
   incremental: boolean;
+  /**
+   * The site's content index (Quartz 5.1+): one entry per published page, virtual pages
+   * included. Available to emitters (except ComponentResources / PageTypeDispatcher); read-only.
+   */
+  contentIndex?: ReadonlyMap<FullSlug, Readonly<ContentDetails>>;
 }
 
 // ============================================================================
@@ -167,7 +228,22 @@ export type QuartzTransformerPlugin<Options extends OptionType = undefined> = (
   opts?: Options,
 ) => QuartzTransformerPluginInstance;
 
-export type QuartzTransformerPluginInstance = {
+/**
+ * Optional hook on every plugin instance (Quartz 5.1+): extra JSON-serialisable fields for a page's
+ * entry in `static/contentIndex.json`. Core fields cannot be overridden; on key collisions between
+ * plugins the first (in plugin order) wins.
+ */
+export type ContentIndexExtension = (args: {
+  ctx: BuildCtx;
+  fileData: QuartzPluginData;
+  entry: Readonly<ContentDetails>;
+}) => Record<string, unknown> | undefined | void;
+
+interface PluginHooks {
+  extendContentIndex?: ContentIndexExtension;
+}
+
+export type QuartzTransformerPluginInstance = PluginHooks & {
   name: string;
   textTransform?: (ctx: BuildCtx, src: string) => string;
   markdownPlugins?: (ctx: BuildCtx) => PluggableList;
@@ -179,7 +255,7 @@ export type QuartzFilterPlugin<Options extends OptionType = undefined> = (
   opts?: Options,
 ) => QuartzFilterPluginInstance;
 
-export type QuartzFilterPluginInstance = {
+export type QuartzFilterPluginInstance = PluginHooks & {
   name: string;
   shouldPublish(ctx: BuildCtx, content: ProcessedContent): boolean;
 };
@@ -194,7 +270,7 @@ export type QuartzEmitterPlugin<Options extends OptionType = undefined> = (
   opts?: Options,
 ) => QuartzEmitterPluginInstance;
 
-export type QuartzEmitterPluginInstance = {
+export type QuartzEmitterPluginInstance = PluginHooks & {
   name: string;
   emit: (
     ctx: BuildCtx,
@@ -239,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 = (
@@ -265,7 +344,7 @@ export type QuartzPageTypePlugin<Options extends OptionType = undefined> = (
   opts?: Options,
 ) => QuartzPageTypePluginInstance;
 
-export type QuartzPageTypePluginInstance = {
+export type QuartzPageTypePluginInstance = PluginHooks & {
   name: string;
   /** Higher priority wins when multiple page types match the same file. Default: 0. */
   priority?: number;
@@ -312,8 +391,20 @@ export interface PageFrameProps {
   right: QuartzComponent[];
   /** Footer components */
   footer: QuartzComponent[];
+  /**
+   * Sidebar modes from `layout.sidebars` (Quartz 5.1+; undefined before). Frames with sidebars
+   * should put them on the sidebar elements as `data-sidebar-mode`; Quartz's stylesheet does the rest.
+   */
+  sidebars?: { left: SidebarMode; right: SidebarMode };
 }
 
+/**
+ * How a sidebar handles content taller than the screen (`layout.sidebars`, Quartz 5.1+):
+ * `fit` (default) — one screen tall, components shrink and scroll; `scroll` — stays in view and
+ * scrolls itself; `static` — scrolls away with the page.
+ */
+export type SidebarMode = "fit" | "scroll" | "static";
+
 /**
  * A PageFrame defines the inner HTML structure of a page inside the
  * `<div id="quartz-root">` shell. Different frames can produce completely
@@ -343,12 +434,7 @@ export type EventHandler = (event: Event) => void;
 export type CleanupFunction = () => void;
 
 export type ClassValue =
-  | string
-  | number
-  | boolean
-  | undefined
-  | null
-  | ClassValue[];
+  string | number | boolean | undefined | null | ClassValue[];
 
 // ============================================================================
 // Content Index Types - Data shape for contentIndex.json
@@ -364,6 +450,8 @@ export type ContentDetails = {
   richContent?: string;
   date?: Date;
   description?: string;
+  /** Fields added by plugins through `extendContentIndex` (Quartz 5.1+). */
+  [extra: string]: unknown;
 };
 
 export type ContentIndex = Record<FullSlug, ContentDetails>;