@quartz-community/og-image 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial Quartz community plugin template.

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,50 @@
+# @quartz-community/og-image
+
+Generates Open Graph social preview images for each page using Satori and Sharp.
+
+## Installation
+
+```bash
+npx quartz plugin add github:quartz-community/og-image
+```
+
+## Usage
+
+```yaml title="quartz.config.yaml"
+plugins:
+  - source: github:quartz-community/og-image
+    enabled: true
+```
+
+For advanced use cases, you can override in TypeScript:
+
+```ts title="quartz.ts (override)"
+import * as ExternalPlugin from "./.quartz/plugins";
+
+ExternalPlugin.CustomOgImages({
+  colorScheme: "lightMode",
+  width: 1200,
+  height: 630,
+});
+```
+
+## Configuration
+
+| Option               | Type                          | Default                     | Description                                                  |
+| -------------------- | ----------------------------- | --------------------------- | ------------------------------------------------------------ |
+| `colorScheme`        | `"lightMode" \| "darkMode"`   | `"lightMode"`               | The color scheme to use for the generated images.            |
+| `width`              | `number`                      | `1200`                      | The width of the generated images.                           |
+| `height`             | `number`                      | `630`                       | The height of the generated images.                          |
+| `excludeRoot`        | `boolean`                     | `false`                     | Whether to exclude the root page from image generation.      |
+| `defaultTitle`       | `string`                      | `"Untitled"`                | The default title to use if a page has no title.             |
+| `defaultDescription` | `string`                      | `"No description provided"` | The default description to use if a page has no description. |
+| `readingTimeText`    | `(minutes: number) => string` | `undefined`                 | A function to format the reading time text.                  |
+| `imageStructure`     | `function`                    | `undefined`                 | A function to define the structure of the generated image.   |
+
+## Documentation
+
+See the [Quartz documentation](https://quartz.jzhao.xyz/plugins/CustomOgImages) for more information.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import { SatoriOptions } from 'satori';
+import { QuartzEmitterPlugin, ThemeKey, GlobalConfiguration, FullSlug } from '@quartz-community/types';
+export { QuartzEmitterPlugin } from '@quartz-community/types';
+import { JSX } from 'preact';
+
+type Frontmatter = {
+    title?: string;
+    description?: string;
+    socialDescription?: string;
+    socialImage?: string;
+    tags?: string[];
+} & Record<string, unknown>;
+/**
+ * Page data passed to user-provided `imageStructure` callbacks.
+ *
+ * This is deliberately narrower than `@quartz-community/types`'
+ * `QuartzPluginData`: it documents exactly which fields the og-image
+ * emitter promises to populate before invoking `imageStructure`. The
+ * extra `text?` field is synthesised by this plugin from the page's
+ * rendered content prior to the callback.
+ *
+ * Do NOT replace this with `QuartzPluginData`: doing so would advertise
+ * fields (e.g. `htmlAst`) that this emitter does not pass through.
+ */
+type SocialImageFileData = {
+    slug?: FullSlug;
+    frontmatter?: Frontmatter;
+    description?: string;
+    text?: string;
+    filePath?: string;
+    dates?: Record<string, Date>;
+};
+type SocialImageOptions = {
+    colorScheme: ThemeKey;
+    height: number;
+    width: number;
+    excludeRoot: boolean;
+    defaultTitle?: string;
+    defaultDescription?: string;
+    readingTimeText?: (minutes: number) => string;
+    imageStructure: (options: ImageOptions & {
+        userOpts: UserOpts;
+        iconBase64?: string;
+    }) => JSX.Element;
+};
+type UserOpts = Omit<SocialImageOptions, "imageStructure">;
+type ImageOptions = {
+    title: string;
+    description: string;
+    fonts: SatoriOptions["fonts"];
+    cfg: GlobalConfiguration;
+    fileData: SocialImageFileData;
+};
+declare const CustomOgImagesEmitterName = "CustomOgImages";
+declare const CustomOgImages: QuartzEmitterPlugin<Partial<SocialImageOptions>>;
+
+export { CustomOgImages, CustomOgImagesEmitterName, type ImageOptions, type SocialImageFileData, type SocialImageOptions, type UserOpts };