@quartz-community/types 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quartz Community
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @quartz-community/types
+
+Type definitions for Quartz community plugins. This package provides TypeScript interfaces and types that mirror the internal Quartz types, enabling external plugins to have full type safety without depending on the core Quartz package.
+
+## Installation
+
+```bash
+npm install @quartz-community/types
+```
+
+## Usage
+
+```typescript
+import {
+  QuartzComponent,
+  QuartzComponentProps,
+  ExplorerOptions,
+} from "@quartz-community/types";
+
+const MyComponent: QuartzComponent = (props: QuartzComponentProps) => {
+  // Component implementation
+};
+
+MyComponent.css = `
+  .my-component { /* styles */ }
+`;
+
+MyComponent.afterDOMLoaded = `
+  // Client-side script
+`;
+```
+
+## Included Types
+
+- **Component Types**: `QuartzComponent`, `QuartzComponentProps`, `StringResource`
+- **Plugin Types**: `QuartzTransformerPlugin`, `QuartzFilterPlugin`, `QuartzEmitterPlugin`
+- **Data Types**: `FileTrieNode`, `ContentIndex`, `ContentIndexEntry`
+- **Component Options**: `ExplorerOptions`, `GraphOptions`, `SearchOptions`, `D3Config`
+- **Utility Types**: `HTMLAttributes`, `EventHandler`, `CleanupFunction`, `ClassValue`
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,307 @@
+import * as hast from 'hast';
+import { Root as Root$1 } from 'hast';
+import { Root } from 'mdast';
+import { VFile, Data } from 'vfile';
+import { PluggableList } from 'unified';
+
+type FilePath = string & {
+    _brand: "FilePath";
+};
+type FullSlug = string & {
+    _brand: "FullSlug";
+};
+type SimpleSlug = string & {
+    _brand: "SimpleSlug";
+};
+declare function joinSegments(...segments: string[]): FilePath;
+type JSResource = {
+    loadTime: "beforeDOMReady" | "afterDOMReady";
+    moduleType?: "module";
+    spaPreserve?: boolean;
+    src: string;
+    contentType: "external";
+} | {
+    loadTime: "beforeDOMReady" | "afterDOMReady";
+    moduleType?: "module";
+    spaPreserve?: boolean;
+    script: string;
+    contentType: "inline";
+};
+type CSSResource = {
+    content: string;
+    inline?: boolean;
+    spaPreserve?: boolean;
+};
+interface StaticResources {
+    css: CSSResource[];
+    js: JSResource[];
+    additionalHead: any[];
+}
+/**
+ * Flat configuration object that components receive as `cfg` prop.
+ * This matches Quartz's `GlobalConfiguration` — the resolved config
+ * passed to components at render time (i.e. `ctx.cfg.configuration`).
+ */
+interface GlobalConfiguration {
+    pageTitle?: string;
+    pageTitleSuffix?: string;
+    enableSPA?: boolean;
+    enablePopovers?: boolean;
+    analytics?: unknown;
+    ignorePatterns?: string[];
+    defaultDateType?: string;
+    baseUrl?: string;
+    theme?: unknown;
+    locale?: string;
+}
+/**
+ * Full Quartz config with nested `configuration` property.
+ * This is what `BuildCtx.cfg` holds — used in plugin hooks
+ * (transformers, filters, emitters), NOT in component props.
+ */
+interface QuartzConfig {
+    configuration: GlobalConfiguration;
+    plugins?: unknown;
+    externalPlugins?: unknown;
+}
+interface Argv {
+    directory: string;
+    verbose: boolean;
+    output: string;
+    serve: boolean;
+    watch: boolean;
+    port: number;
+    wsPort: number;
+    remoteDevHost?: string;
+    concurrency?: number;
+}
+interface BuildCtx {
+    buildId: string;
+    argv: Argv;
+    cfg: QuartzConfig;
+    allSlugs: FullSlug[];
+    allFiles: FilePath[];
+    incremental: boolean;
+}
+type QuartzPluginData = Data;
+type MarkdownContent = [Root, VFile];
+type ProcessedContent = [Root$1, VFile];
+type QuartzComponentProps = {
+    ctx: unknown;
+    externalResources: StaticResources;
+    fileData: QuartzPluginData & Record<string, unknown>;
+    cfg: GlobalConfiguration;
+    children: unknown;
+    tree: unknown;
+    allFiles: (QuartzPluginData & Record<string, unknown>)[];
+    displayClass?: "mobile-only" | "desktop-only";
+    [key: string]: unknown;
+};
+type QuartzComponent = ((props: QuartzComponentProps) => unknown) & {
+    css?: string | string[] | undefined;
+    beforeDOMLoaded?: string | string[] | undefined;
+    afterDOMLoaded?: string | string[] | undefined;
+};
+type QuartzComponentConstructor<Options extends object | undefined = undefined> = (opts?: Options) => QuartzComponent;
+type StringResource = string | string[];
+type OptionType = object | undefined;
+type ExternalResourcesFn = (ctx: BuildCtx) => Partial<StaticResources> | undefined;
+
+interface PluginTypes {
+    transformers: QuartzTransformerPluginInstance[];
+    filters: QuartzFilterPluginInstance[];
+    emitters: QuartzEmitterPluginInstance[];
+    pageTypes: QuartzPageTypePluginInstance[];
+}
+type QuartzTransformerPlugin<Options extends OptionType = undefined> = (opts?: Options) => QuartzTransformerPluginInstance;
+type QuartzTransformerPluginInstance = {
+    name: string;
+    textTransform?: (ctx: BuildCtx, src: string) => string;
+    markdownPlugins?: (ctx: BuildCtx) => PluggableList;
+    htmlPlugins?: (ctx: BuildCtx) => PluggableList;
+    externalResources?: ExternalResourcesFn;
+};
+type QuartzFilterPlugin<Options extends OptionType = undefined> = (opts?: Options) => QuartzFilterPluginInstance;
+type QuartzFilterPluginInstance = {
+    name: string;
+    shouldPublish(ctx: BuildCtx, content: ProcessedContent): boolean;
+};
+type ChangeEvent = {
+    type: "add" | "change" | "delete";
+    path: FilePath;
+    file?: VFile;
+};
+type QuartzEmitterPlugin<Options extends OptionType = undefined> = (opts?: Options) => QuartzEmitterPluginInstance;
+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;
+    getQuartzComponents?: (ctx: BuildCtx) => QuartzComponent[];
+    externalResources?: ExternalResourcesFn;
+};
+/**
+ * Matcher function: determines if a source file belongs to a page type.
+ * Returns true if the page type should own this file.
+ */
+type PageMatcher = (args: {
+    slug: FullSlug;
+    fileData: QuartzPluginData & Record<string, unknown>;
+    cfg: GlobalConfiguration;
+}) => boolean;
+/**
+ * Virtual page descriptor for page types that generate pages
+ * from aggregated data (e.g., tag indexes, folder listings).
+ */
+interface VirtualPage {
+    slug: FullSlug;
+    title: string;
+    data: Partial<QuartzPluginData> & Record<string, unknown>;
+}
+/**
+ * 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).
+ */
+type PageGenerator = (args: {
+    content: ProcessedContent[];
+    cfg: GlobalConfiguration;
+    ctx: BuildCtx;
+}) => 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;
+/**
+ * A PageType plugin definition.
+ *
+ * PageTypes are a declarative abstraction over page-rendering emitters.
+ * Each PageType declares which files it owns (via `match`), optionally
+ * generates virtual pages (via `generate`), and provides a body component
+ * and layout reference for rendering.
+ */
+type QuartzPageTypePlugin<Options extends OptionType = undefined> = (opts?: Options) => QuartzPageTypePluginInstance;
+type QuartzPageTypePluginInstance = {
+    name: string;
+    /** Higher priority wins when multiple page types match the same file. Default: 0. */
+    priority?: number;
+    /** 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. */
+    fileExtensions?: string[];
+    /** Determines which source files this page type owns. */
+    match: PageMatcher;
+    /** Produces virtual pages from aggregated content data. */
+    generate?: PageGenerator;
+    /** Layout key — references a key in `layout.byPageType`. */
+    layout: string;
+    /** Optional page frame name (e.g. "default", "full-width", "canvas"). Defaults to "default". */
+    frame?: string;
+    /** The body component constructor for this page type. */
+    body: QuartzComponentConstructor;
+    /** Optional render-time HAST tree transforms (e.g. resolving inline codeblocks). */
+    treeTransforms?: (ctx: BuildCtx) => TreeTransform[];
+};
+/**
+ * Props passed to a PageFrame's render function.
+ * Contains the resolved layout components and the shared component data.
+ */
+interface PageFrameProps {
+    /** Component data shared across all components on the page */
+    componentData: QuartzComponentProps;
+    /** The Head component (rendered in <head>) — NOT used by frames, included for completeness */
+    head: QuartzComponent;
+    /** Header slot components (rendered inside <header>) */
+    header: QuartzComponent[];
+    /** Components rendered before the page body */
+    beforeBody: QuartzComponent[];
+    /** The page body component (Content) */
+    pageBody: QuartzComponent;
+    /** Components rendered after the page body */
+    afterBody: QuartzComponent[];
+    /** Left sidebar components */
+    left: QuartzComponent[];
+    /** Right sidebar components */
+    right: QuartzComponent[];
+    /** Footer component */
+    footer: QuartzComponent;
+}
+/**
+ * A PageFrame defines the inner HTML structure of a page inside the
+ * `<div id="quartz-root">` shell. Different frames can produce completely
+ * different layouts (e.g. with/without sidebars, horizontal scroll, etc.)
+ * while the outer shell (html, head, body, quartz-root) remains stable
+ * for SPA navigation.
+ *
+ * The `render` function returns `unknown` to avoid coupling to a specific
+ * JSX runtime (Preact, React, etc.). Quartz core casts this to JSX.Element.
+ */
+interface PageFrame {
+    /** Unique name for this frame (e.g. "default", "full-width", "canvas") */
+    name: string;
+    /** Render the inner page structure. Returns a JSX tree to be placed inside Body > #quartz-body. */
+    render: (props: PageFrameProps) => unknown;
+    /** Optional CSS string to include when this frame is active */
+    css?: string;
+}
+type HTMLAttributes = Record<string, string | number | boolean | undefined>;
+type EventHandler = (event: Event) => void;
+type CleanupFunction = () => void;
+type ClassValue = string | number | boolean | undefined | null | ClassValue[];
+type ContentDetails = {
+    slug: FullSlug;
+    filePath: FilePath;
+    title: string;
+    links: string[];
+    tags: string[];
+    content: string;
+    richContent?: string;
+    date?: Date;
+    description?: string;
+};
+type ContentIndex = Record<FullSlug, ContentDetails>;
+type SortFn = (f1: QuartzPluginData, f2: QuartzPluginData) => number;
+type ThemeKey = "lightMode" | "darkMode";
+type ValidDateType = "created" | "modified" | "published";
+declare module "vfile" {
+    interface DataMap {
+        slug: FullSlug;
+        filePath: FilePath;
+        relativePath: FilePath;
+        description: string;
+        text: string;
+        links: SimpleSlug[];
+        toc: {
+            depth: number;
+            text: string;
+            slug: string;
+        }[];
+        collapseToc: boolean;
+        blocks: Record<string, hast.Element>;
+        htmlAst: hast.Root;
+        hasMermaidDiagram: boolean | undefined;
+        frontmatter: {
+            [key: string]: unknown;
+        } & {
+            title: string;
+        } & Partial<{
+            tags: string[];
+            aliases: string[];
+            modified: string;
+            created: string;
+            published: string;
+            description: string;
+            socialDescription: string;
+            publish: boolean | string;
+            draft: boolean | string;
+            lang: string;
+            enableToc: string;
+            cssclasses: string[];
+            socialImage: string;
+            comments: boolean | string;
+        }>;
+        dates: {
+            created: Date;
+            modified: Date;
+            published: Date;
+        };
+        defaultDateType?: ValidDateType;
+    }
+}
+
+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 };

package/dist/index.js

@@ -0,0 +1,8 @@
+// src/index.ts
+function joinSegments(...segments) {
+  return segments.filter((segment) => segment.length > 0).join("/").replace(/\/+/g, "/");
+}
+export {
+  joinSegments
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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 component */\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":[]}

package/globals.d.ts

@@ -0,0 +1,32 @@
+import type { ContentIndex, FullSlug } from "./dist/index.js";
+
+declare global {
+  interface CustomEventMap {
+    nav: CustomEvent<{ url: FullSlug }>;
+    prenav: CustomEvent<undefined>;
+    themechange: CustomEvent<{ theme: "light" | "dark" }>;
+    readermodechange: CustomEvent<{ mode: "on" | "off" }>;
+    render: CustomEvent<object>;
+  }
+
+  interface Document {
+    addEventListener<K extends keyof CustomEventMap>(
+      type: K,
+      listener: (this: Document, ev: CustomEventMap[K]) => void,
+    ): void;
+    removeEventListener<K extends keyof CustomEventMap>(
+      type: K,
+      listener: (this: Document, ev: CustomEventMap[K]) => void,
+    ): void;
+    dispatchEvent<K extends keyof CustomEventMap>(
+      ev: CustomEventMap[K] | UIEvent,
+    ): void;
+  }
+
+  interface Window {
+    addCleanup(fn: (...args: unknown[]) => void): void;
+    spaNavigate?(url: URL, isBack: boolean): Promise<void>;
+  }
+
+  const fetchData: Promise<ContentIndex>;
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@quartz-community/types",
+  "version": "0.2.1",
+  "description": "Type definitions for Quartz community plugins",
+  "type": "module",
+  "license": "MIT",
+  "author": "Quartz Community",
+  "homepage": "https://quartz.jzhao.xyz",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quartz-community/types"
+  },
+  "keywords": [
+    "quartz",
+    "quartz-plugin",
+    "types",
+    "typescript"
+  ],
+  "files": [
+    "src",
+    "dist",
+    "globals.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./globals": {
+      "types": "./globals.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "unified": "^11.0.5",
+    "vfile": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=22",
+    "npm": ">=10.9.2"
+  },
+  "devDependencies": {
+    "@types/hast": "^3.0.4",
+    "@types/mdast": "^4.0.4",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "unified": "^11.0.5",
+    "vfile": "^6.0.3"
+  },
+  "peerDependenciesMeta": {
+    "unified": {
+      "optional": true
+    },
+    "vfile": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,423 @@
+import type { Root as HtmlRoot } from "hast";
+import type { Root as MdRoot } from "mdast";
+import type { Data, VFile } from "vfile";
+import type { PluggableList } from "unified";
+
+// ============================================================================
+// Path Types - Branded string types for type-safe file paths
+// ============================================================================
+
+export type FilePath = string & { _brand: "FilePath" };
+export type FullSlug = string & { _brand: "FullSlug" };
+export type SimpleSlug = string & { _brand: "SimpleSlug" };
+
+export function joinSegments(...segments: string[]): FilePath {
+  return segments
+    .filter((segment) => segment.length > 0)
+    .join("/")
+    .replace(/\/+/g, "/") as FilePath;
+}
+
+// ============================================================================
+// Resource Types - CSS/JS resources that plugins can inject
+// ============================================================================
+
+export type JSResource =
+  | {
+      loadTime: "beforeDOMReady" | "afterDOMReady";
+      moduleType?: "module";
+      spaPreserve?: boolean;
+      src: string;
+      contentType: "external";
+    }
+  | {
+      loadTime: "beforeDOMReady" | "afterDOMReady";
+      moduleType?: "module";
+      spaPreserve?: boolean;
+      script: string;
+      contentType: "inline";
+    };
+
+export type CSSResource = {
+  content: string;
+  inline?: boolean;
+  spaPreserve?: boolean;
+};
+
+export interface StaticResources {
+  css: CSSResource[];
+  js: JSResource[];
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  additionalHead: any[];
+}
+
+// ============================================================================
+// Config Types - Quartz configuration
+// ============================================================================
+
+/**
+ * Flat configuration object that components receive as `cfg` prop.
+ * This matches Quartz's `GlobalConfiguration` — the resolved config
+ * passed to components at render time (i.e. `ctx.cfg.configuration`).
+ */
+export interface GlobalConfiguration {
+  pageTitle?: string;
+  pageTitleSuffix?: string;
+  enableSPA?: boolean;
+  enablePopovers?: boolean;
+  analytics?: unknown;
+  ignorePatterns?: string[];
+  defaultDateType?: string;
+  baseUrl?: string;
+  theme?: unknown;
+  locale?: string;
+}
+
+/**
+ * Full Quartz config with nested `configuration` property.
+ * This is what `BuildCtx.cfg` holds — used in plugin hooks
+ * (transformers, filters, emitters), NOT in component props.
+ */
+export interface QuartzConfig {
+  configuration: GlobalConfiguration;
+  plugins?: unknown;
+  externalPlugins?: unknown;
+}
+
+// ============================================================================
+// Context Types - Build context passed to plugin hooks
+// ============================================================================
+
+export interface Argv {
+  directory: string;
+  verbose: boolean;
+  output: string;
+  serve: boolean;
+  watch: boolean;
+  port: number;
+  wsPort: number;
+  remoteDevHost?: string;
+  concurrency?: number;
+}
+
+export interface BuildCtx {
+  buildId: string;
+  argv: Argv;
+  cfg: QuartzConfig;
+  allSlugs: FullSlug[];
+  allFiles: FilePath[];
+  incremental: boolean;
+}
+
+// ============================================================================
+// VFile Types - Content data types
+// ============================================================================
+
+export type QuartzPluginData = Data;
+export type MarkdownContent = [MdRoot, VFile];
+export type ProcessedContent = [HtmlRoot, VFile];
+
+// ============================================================================
+// Core Component Types - The contract between Quartz and plugins
+// ============================================================================
+
+export type QuartzComponentProps = {
+  ctx: unknown;
+  externalResources: StaticResources;
+  fileData: QuartzPluginData & Record<string, unknown>;
+  cfg: GlobalConfiguration;
+  children: unknown;
+  tree: unknown;
+  allFiles: (QuartzPluginData & Record<string, unknown>)[];
+  displayClass?: "mobile-only" | "desktop-only";
+  [key: string]: unknown;
+};
+
+export type QuartzComponent = ((props: QuartzComponentProps) => unknown) & {
+  css?: string | string[] | undefined;
+  beforeDOMLoaded?: string | string[] | undefined;
+  afterDOMLoaded?: string | string[] | undefined;
+};
+
+export type QuartzComponentConstructor<
+  Options extends object | undefined = undefined,
+> = (opts?: Options) => QuartzComponent;
+
+export type StringResource = string | string[];
+
+// ============================================================================
+// Plugin Types - What Quartz expects from plugins
+// ============================================================================
+
+type OptionType = object | undefined;
+type ExternalResourcesFn = (
+  ctx: BuildCtx,
+) => Partial<StaticResources> | undefined;
+
+export type { ExternalResourcesFn };
+
+export interface PluginTypes {
+  transformers: QuartzTransformerPluginInstance[];
+  filters: QuartzFilterPluginInstance[];
+  emitters: QuartzEmitterPluginInstance[];
+  pageTypes: QuartzPageTypePluginInstance[];
+}
+
+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;
+  getQuartzComponents?: (ctx: BuildCtx) => QuartzComponent[];
+  externalResources?: ExternalResourcesFn;
+};
+
+// ============================================================================
+// PageType Plugin Types - Declarative page rendering plugins
+// ============================================================================
+
+/**
+ * Matcher function: determines if a source file belongs to a page type.
+ * Returns true if the page type should own this file.
+ */
+export type PageMatcher = (args: {
+  slug: FullSlug;
+  fileData: QuartzPluginData & Record<string, unknown>;
+  cfg: GlobalConfiguration;
+}) => boolean;
+
+/**
+ * Virtual page descriptor for page types that generate pages
+ * from aggregated data (e.g., tag indexes, folder listings).
+ */
+export interface VirtualPage {
+  slug: FullSlug;
+  title: string;
+  data: Partial<QuartzPluginData> & Record<string, unknown>;
+}
+
+/**
+ * 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).
+ */
+export type PageGenerator = (args: {
+  content: ProcessedContent[];
+  cfg: GlobalConfiguration;
+  ctx: BuildCtx;
+}) => VirtualPage[];
+
+/** A function that mutates a HAST tree at render time, when allFiles is available. */
+export type TreeTransform = (
+  root: HtmlRoot,
+  slug: FullSlug,
+  componentData: QuartzComponentProps,
+) => void;
+
+/**
+ * A PageType plugin definition.
+ *
+ * PageTypes are a declarative abstraction over page-rendering emitters.
+ * Each PageType declares which files it owns (via `match`), optionally
+ * generates virtual pages (via `generate`), and provides a body component
+ * and layout reference for rendering.
+ */
+export type QuartzPageTypePlugin<Options extends OptionType = undefined> = (
+  opts?: Options,
+) => QuartzPageTypePluginInstance;
+
+export type QuartzPageTypePluginInstance = {
+  name: string;
+  /** Higher priority wins when multiple page types match the same file. Default: 0. */
+  priority?: number;
+  /** 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. */
+  fileExtensions?: string[];
+  /** Determines which source files this page type owns. */
+  match: PageMatcher;
+  /** Produces virtual pages from aggregated content data. */
+  generate?: PageGenerator;
+  /** Layout key — references a key in `layout.byPageType`. */
+  layout: string;
+  /** Optional page frame name (e.g. "default", "full-width", "canvas"). Defaults to "default". */
+  frame?: string;
+  /** The body component constructor for this page type. */
+  body: QuartzComponentConstructor;
+  /** Optional render-time HAST tree transforms (e.g. resolving inline codeblocks). */
+  treeTransforms?: (ctx: BuildCtx) => TreeTransform[];
+};
+
+// ============================================================================
+// PageFrame Types — Custom page layout frames
+// ============================================================================
+
+/**
+ * Props passed to a PageFrame's render function.
+ * Contains the resolved layout components and the shared component data.
+ */
+export interface PageFrameProps {
+  /** Component data shared across all components on the page */
+  componentData: QuartzComponentProps;
+  /** The Head component (rendered in <head>) — NOT used by frames, included for completeness */
+  head: QuartzComponent;
+  /** Header slot components (rendered inside <header>) */
+  header: QuartzComponent[];
+  /** Components rendered before the page body */
+  beforeBody: QuartzComponent[];
+  /** The page body component (Content) */
+  pageBody: QuartzComponent;
+  /** Components rendered after the page body */
+  afterBody: QuartzComponent[];
+  /** Left sidebar components */
+  left: QuartzComponent[];
+  /** Right sidebar components */
+  right: QuartzComponent[];
+  /** Footer component */
+  footer: QuartzComponent;
+}
+
+/**
+ * A PageFrame defines the inner HTML structure of a page inside the
+ * `<div id="quartz-root">` shell. Different frames can produce completely
+ * different layouts (e.g. with/without sidebars, horizontal scroll, etc.)
+ * while the outer shell (html, head, body, quartz-root) remains stable
+ * for SPA navigation.
+ *
+ * The `render` function returns `unknown` to avoid coupling to a specific
+ * JSX runtime (Preact, React, etc.). Quartz core casts this to JSX.Element.
+ */
+export interface PageFrame {
+  /** Unique name for this frame (e.g. "default", "full-width", "canvas") */
+  name: string;
+  /** Render the inner page structure. Returns a JSX tree to be placed inside Body > #quartz-body. */
+  render: (props: PageFrameProps) => unknown;
+  /** Optional CSS string to include when this frame is active */
+  css?: string;
+}
+
+export type HTMLAttributes = Record<
+  string,
+  string | number | boolean | undefined
+>;
+
+export type EventHandler = (event: Event) => void;
+
+export type CleanupFunction = () => void;
+
+export type ClassValue =
+  | string
+  | number
+  | boolean
+  | undefined
+  | null
+  | ClassValue[];
+
+// ============================================================================
+// Content Index Types - Data shape for contentIndex.json
+// ============================================================================
+
+export type ContentDetails = {
+  slug: FullSlug;
+  filePath: FilePath;
+  title: string;
+  links: string[];
+  tags: string[];
+  content: string;
+  richContent?: string;
+  date?: Date;
+  description?: string;
+};
+
+export type ContentIndex = Record<FullSlug, ContentDetails>;
+
+// ============================================================================
+// Sort & Theme Types
+// ============================================================================
+
+export type SortFn = (f1: QuartzPluginData, f2: QuartzPluginData) => number;
+
+export type ThemeKey = "lightMode" | "darkMode";
+
+export type ValidDateType = "created" | "modified" | "published";
+
+// ============================================================================
+// VFile DataMap Augmentation — canonical vfile shape for Quartz
+// ============================================================================
+
+declare module "vfile" {
+  interface DataMap {
+    slug: FullSlug;
+    filePath: FilePath;
+    relativePath: FilePath;
+    description: string;
+    text: string;
+    links: SimpleSlug[];
+    toc: { depth: number; text: string; slug: string }[];
+    collapseToc: boolean;
+    blocks: Record<string, import("hast").Element>;
+    htmlAst: import("hast").Root;
+    hasMermaidDiagram: boolean | undefined;
+    frontmatter: { [key: string]: unknown } & {
+      title: string;
+    } & Partial<{
+        tags: string[];
+        aliases: string[];
+        modified: string;
+        created: string;
+        published: string;
+        description: string;
+        socialDescription: string;
+        publish: boolean | string;
+        draft: boolean | string;
+        lang: string;
+        enableToc: string;
+        cssclasses: string[];
+        socialImage: string;
+        comments: boolean | string;
+      }>;
+    dates: {
+      created: Date;
+      modified: Date;
+      published: Date;
+    };
+    defaultDateType?: ValidDateType;
+  }
+}