@docubook/plugin-og-image 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wildan Nursahidan
+
+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

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @docubook/plugin-og-image
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Social preview cards for [DocuBook Flame](https://github.com/DocuBook/docubook/tree/main/packages/flame). Every page gets a 1200×630 OpenGraph image built from its frontmatter, with your logo, site name and theme colours. Authors write nothing extra: `title` and `description` are enough.
+
+Cards are rendered at build time with [Takumi](https://github.com/kane50613/takumi), a native renderer that needs no browser. A card takes a few milliseconds, and a build only renders the cards whose text or branding changed.
+
+## Install
+
+```bash
+npm install -D @docubook/plugin-og-image
+```
+
+```json
+{
+  "meta": {
+    "baseURL": "https://docs.example.com"
+  },
+  "plugins": ["@docubook/plugin-og-image"]
+}
+```
+
+Set `meta.baseURL`: social sites only read absolute image URLs.
+
+## What it does
+
+- Sets each docs page's `image` to its card, so Flame writes the `og:image` tag as it does for an image you set yourself.
+- Adds `og:image:width`, `og:image:height`, `og:image:type` and `og:image:alt`.
+- Gives the landing page a card too, unless `meta.ogImage` already sets its image.
+- Writes the cards to `<docs prefix>/assets/og/`, e.g. `/docs/assets/og/guides/setup.1a2b3c4d.png`. The hash in the name changes with the card's text, so social sites fetch the new card instead of a cached one.
+- Serves the same cards from `flame dev`.
+
+A page keeps its own image when its frontmatter sets `image`. `og: false` turns the card off for one page; `og.title` and `og.description` change the card's text without touching the page.
+
+```yaml
+---
+title: Configuration reference for docu.json
+description: Every option in docu.json.
+og:
+  title: Configuration
+---
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `layout` | `"card"` \| `"minimal"` | `"card"` | `card` adds the section name, a page-kind chip, a logo tile and a brand bar. `minimal` shows logo, title, description and domain on a plain background. |
+| `logo` | string \| `false` | `navbar.logo.src` | Logo file: a project path (`brand/logo.svg`) or a site path (`/docs/assets/logo.svg`). SVG, PNG, JPEG or WebP, at most 1 MB. `false` renders no logo. |
+| `siteName` | string | `navbar.logoText`, then `meta.title` | Name in the card's top row. |
+| `pages` | `{ docs?, index?, home? }` | all `true` | Which pages get a card. |
+| `fonts` | `{ path, weight?, style? }[]` | none | Fonts tried before the built-in Geist, which covers Latin-1 only. Add one for titles in other scripts. |
+
+The build warns when a title has characters no loaded font can draw, and names the pages.
+
+## How it works
+
+`transformFrontmatter` sets `image: ./assets/og/<slug>.<hash>.png`, which Flame resolves against `meta.baseURL` and the docs prefix. Cards take their text from the frontmatter in the source file, so a title another plugin changes at build time (in `onLoad` or `transformFrontmatter`) does not reach the card; the file name the page links to and the file `onEnd` writes always match. `onEnd` reads every page's frontmatter, renders the cards that are missing or out of date, deletes cards of removed pages, and records what it wrote in `.docu/og-image.json`. Takumi's `render()` never touches the network: the logo and fonts are read from disk.
+
+## Development
+
+```bash
+pnpm --filter @docubook/plugin-og-image build
+pnpm --filter @docubook/plugin-og-image test
+UPDATE_GOLDEN=1 pnpm --filter @docubook/plugin-og-image test   # after an intended layout change
+```
+
+The golden-image tests compare against `src/__tests__/__golden__/` on Linux x64 only, where CI runs.

package/dist/cards.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Turning a page into a card: what text it shows, whether it is skipped, and
+ * the file name it is published under. Pure functions over frontmatter.
+ */
+import type { DocuConfig } from "@docubook/flame";
+import type { ResolvedOptions } from "./options";
+import { type Site } from "./site";
+export type CardKind = "docs" | "index" | "home";
+export interface Card {
+    kind: CardKind;
+    /** Docs slug; `""` for the docs index and the landing page. */
+    slug: string;
+    title: string;
+    description: string;
+    /** Top-level sidebar group, docs pages only. */
+    section: string | undefined;
+}
+export interface PlannedCard {
+    card: Card;
+    /** File name below `assets/og/`, e.g. `guide/routing.1a2b3c4d.png`. */
+    file: string;
+    /** Hash of everything flame's page cache also sees; its first 8 chars name the file. */
+    nameHash: string;
+}
+export type SkipReason = "disabled" | "author-image" | "opt-out";
+/**
+ * Why a page gets no card, or `undefined` when it gets one. An image the
+ * author set always wins; `og: false` opts the page out.
+ */
+export declare function skipReason(kind: CardKind, frontmatter: Record<string, unknown>, options: ResolvedOptions): SkipReason | undefined;
+/** Card text for a docs page or the docs index. Mirrors flame's title fallback. */
+export declare function docsCard(kind: "docs" | "index", slug: string, frontmatter: Record<string, unknown>, site: Site): Card;
+/** Card text for the landing page: the hero headline and the site description. */
+export declare function homeCard(config: DocuConfig): Card;
+export declare function sha256(...parts: Array<string | Uint8Array>): string;
+/**
+ * Plan a card's file. The name hash covers only inputs that also invalidate
+ * flame's page cache (plugin version, `docu.json`, the page's source), so a
+ * page served from that cache always points at a file this build writes.
+ */
+export declare function planCard(card: Card, site: Site, options: ResolvedOptions, version: string): PlannedCard;
+/** The value set as `frontmatter.image`; flame resolves it against the docs prefix. */
+export declare function imageRef(file: string): string;
+/** Source file candidates for a slug, in the order flame's scanner would find them. */
+export declare function sourceCandidates(docsDir: string, slug: string): string[];
+/**
+ * Frontmatter of a docs page as written in its source file, or `undefined`
+ * when no source exists. Every card is planned from this, never from the
+ * frontmatter other plugins hand on, so the page phase and `onEnd` always
+ * agree on the file name.
+ */
+export declare function readFrontmatter(docsDir: string, slug: string): Promise<Record<string, unknown> | undefined>;
+/** {@link readFrontmatter} for hooks that must return synchronously. */
+export declare function readFrontmatterSync(docsDir: string, slug: string): Record<string, unknown> | undefined;

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @docubook/plugin-og-image
+ *
+ * Gives every page a 1200×630 social preview card, rendered at build time
+ * from the page's frontmatter with Takumi. Authors write nothing extra:
+ *
+ * - `transformFrontmatter` points `frontmatter.image` at the page's card, and
+ *   flame's own SEO code turns it into an absolute `og:image`;
+ * - `injectHead` adds the card's size, type and alt text, and an `og:image`
+ *   on the landing page when `meta.ogImage` does not set one;
+ * - `onEnd` renders the cards into `<docs>/assets/og/`, skipping the ones
+ *   whose inputs did not change;
+ * - `handleRequest` renders a card on demand during `flame dev`.
+ *
+ * An `image` in frontmatter always wins, and `og: false` opts a page out.
+ */
+import type { DocuBookPlugin, DocuConfig } from "@docubook/flame";
+import { type Palette } from "./layouts";
+import { type OgImageOptions } from "./options";
+import { type Engine, type LoadedFont } from "./renderer";
+export type { FontOption, Layout, OgImageOptions, PagesOption } from "./options";
+/** Logos above this size are skipped: a card shows them at 140 px. */
+export declare const MAX_LOGO_BYTES: number;
+export interface Logger {
+    info(message: string): void;
+    warn(message: string): void;
+}
+export interface PluginInternals {
+    /** @internal Project root instead of the `docu.json` lookup from `cwd` (tests). */
+    root?: string;
+    /** @internal Log sink (tests). */
+    log?: Logger;
+    /** @internal Renderer factory (tests). */
+    createEngine?: (fonts: LoadedFont[]) => Promise<Engine>;
+    /** @internal Plugin version that goes into card names (tests). */
+    version?: string;
+}
+/** Light-mode colours of the active theme, as flame resolves it. */
+export declare function resolvePalette(config: DocuConfig): Palette;
+export default function pluginOgImage(options?: OgImageOptions, internals?: PluginInternals): DocuBookPlugin;