See the output.
Then copy the code.

Quick start

Install the package with your preferred package manager, initialize a preset config, and generate the first image.

pnpm add -D @santi020k/og

npm install -D @santi020k/og

yarn add -D @santi020k/og

pnpm exec santi-og init
pnpm exec santi-og generate
pnpm exec santi-og check
pnpm exec santi-og compare --threshold 0.01
pnpm exec santi-og migrate --report --json
pnpm exec santi-og upgrade --to 0.4.0

santi-og init now creates a preset-based configuration. It works immediately; writing SVG is optional.

Choose your starting point

import { createPathCards } from '@santi020k/og'
import { definePresetConfig } from '@santi020k/og/presets'

export default definePresetConfig({
  outputDirectory: 'public/og/pages',
  cards: createPathCards([
    {
      pathname: '/',
      data: {
        title: 'Ship the card. Delete the renderer.',
        description: 'A complete social image from a small config.',
        badge: 'Product',
        variant: 'product',
      },
    },
  ]),
  preset: {
    brand: {
      name: 'Example',
      domain: 'example.com',
      logo: 'public/logo.png',
    },
    theme: { accent: '#7c3aed' },
  },
})

import { collectContentCards } from '@santi020k/og/content'
import { definePresetConfig } from '@santi020k/og/presets'

export default definePresetConfig({
  outputDirectory: 'public/og',
  cards: () => collectContentCards({
    directory: 'src/content/blog',
    basePath: 'blog',
    map: entry => ({
      title: String(entry.frontmatter.title),
      description: String(entry.frontmatter.description ?? ''),
      ...(typeof entry.frontmatter.cover === 'string'
        ? { image: entry.frontmatter.cover }
        : {}),
      variant: 'article',
    }),
    sources: entry => typeof entry.frontmatter.cover === 'string'
      ? [entry.filePath, entry.frontmatter.cover]
      : [entry.filePath],
  }),
  preset: {
    brand: { name: 'Example Journal' },
    variant: 'article',
  },
})

import { defineConfig } from '@santi020k/og'
import { createSharpRenderer } from '@santi020k/og/sharp'

export default defineConfig({
  cards: [{ output: 'index.webp', data: { title: 'Home' } }],
  renderer: createSharpRenderer({
    renderSvg: ({ title }, { height, width }) =>
      `<svg viewBox="0 0 ${width} ${height}">...</svg>`,
    webp: { quality: 86 },
  }),
})

Visual presets

Every preset shares the same accessible title, description, badge, brand, logo, domain, accent, and image data contract. Bundled Inter typography and glyph-aware wrapping make output portable across build machines. A config-level variant is the default; any card can override it.

Simple

A clean default for home pages, status pages, and general sharing.

variant: 'simple'

Article

Editorial composition for posts, guides, changelogs, and announcements.

variant: 'article'

Docs

Structured visual language for references, component docs, and tutorials.

variant: 'docs'

Product

Product-focused framing for apps, tools, launches, and landing pages.

variant: 'product'

Theme and card overrides

Set preset.brand, preset.theme, and preset.variant once. Override accent, brand, domain, image, or variant on individual cards.

Generated preset SVG uses portable fill and stroke opacity attributes instead of CSS rgba() colors, improving compatibility with SVG validators and consumer tooling.

Page metadata from the same source

definePageMetadata keeps the title, description, route, and social image together. Derive a card with an explicit renderer mapping, portable tag descriptors, escaped HTML, or a Next.js Metadata API object without adding a framework runtime.

import { createMetaTags, createPageCard, definePageMetadata } from '@santi020k/og/metadata'
import { renderMetaTags } from '@santi020k/og/metadata/html'
import { toNextMetadata } from '@santi020k/og/metadata/next'

export const page = definePageMetadata({
  pathname: '/docs',
  title: 'Documentation',
  description: 'Learn how to generate deterministic social images.',
  image: {
    output: 'pages/docs.webp',
    alt: 'Example documentation social card',
    width: 1200,
    height: 630,
  },
})

export const card = createPageCard(page, {
  data: ({ description, title }) => ({
    title,
    description,
    badge: 'Guide',
    variant: 'docs',
  }),
})

const site = { siteUrl: 'https://example.com', siteName: 'Example' }
export const tags = createMetaTags(page, site)
export const html = renderMetaTags(tags)
export const metadata = toNextMetadata(page, site)

The helpers resolve absolute canonical and image URLs, infer image MIME types, include dimensions and alternative text, remove canonical fragments, and validate empty text or invalid dimensions. Article pages can add dates, authors, section, and tags.

Metadata functions

Page definition

Site defaults

Framework-neutral Markdown and MDX

collectContentCards reads YAML frontmatter without starting Astro, Next.js, or another framework. It understands nested index.md routes, excludes drafts by default, and tracks each content file as a source.

import { collectContentCards } from '@santi020k/og/content'
import { definePresetConfig } from '@santi020k/og/presets'

export default definePresetConfig({
  outputDirectory: 'public/og',
  cards: () => collectContentCards({
    directory: 'src/content/blog',
    basePath: 'blog',
    map: entry => ({
      title: String(entry.frontmatter.title),
      description: String(entry.frontmatter.description ?? ''),
      ...(typeof entry.frontmatter.cover === 'string'
        ? { image: entry.frontmatter.cover }
        : {}),
      variant: 'article',
    }),
    sources: entry => typeof entry.frontmatter.cover === 'string'
      ? [entry.filePath, entry.frontmatter.cover]
      : [entry.filePath],
  }),
  preset: {
    brand: { name: 'Example Journal' },
    variant: 'article',
  },
})

Use readContent when you only need the normalized entries. Each entry exposes its body, absolute file path, parsed frontmatter, directory-relative ID, and nested-index-aware slug.

Existing @santi020k/og/astro imports remain compatibility aliases for the same implementation.

Typed catalogs and derived collections

createCards maps arrays, JSON, CMS results, products, tag archives, or pagination into typed cards without consumer-side expansion. Shared output rules, sources, dimensions, formats, and aliases stay in one place.

import { createCards } from '@santi020k/og'

const cards = createCards(products, product => ({
  title: product.name,
  description: product.summary,
  image: product.image,
  variant: 'product',
}), {
  output: product => 'products/' + product.slug + '.webp',
  formats: ['png', 'svg'],
  formatAliases: product => ({
    png: ['social/' + product.slug + '.png'],
  }),
  sources: product => product.image ? [product.image] : [],
})

The mapper receives the item and index. Every option callback receives the original item, mapped card data, and index, so output names and cache sources can use either representation. formats applies to every logical card; formatAliases can derive encoding-specific destinations per item.

Route-oriented cards

pathnameOutput and createPathCards remove repeated slug and output mapping from route-heavy sites. URL segments are encoded into portable, deterministic filenames.

import { createPathCards, pathnameOutput } from '@santi020k/og'

pathnameOutput('/')                       // index.webp
pathnameOutput('/docs/api')               // docs--api.webp
pathnameOutput('/guides/getting started') // guides--getting~20started.webp

const cards = createPathCards(pages, {
  directory: 'routes',
  extension: 'png',
})

Custom renderers

Use a custom renderer for bespoke editorial art, data visualization, or strict legacy parity. The generation pipeline stays the same.

import { defineConfig } from '@santi020k/og'
import { createSharpRenderer } from '@santi020k/og/sharp'

export default defineConfig({
  cards: [{ output: 'index.webp', data: { title: 'Home' } }],
  renderer: createSharpRenderer({
    renderSvg: ({ title }, { height, width }) =>
      `<svg viewBox="0 0 ${width} ${height}">...</svg>`,
    webp: { quality: 86 },
  }),
})

import { readFile } from 'node:fs/promises'
import { defineConfig } from '@santi020k/og'
import { createSatoriRenderer, html } from '@santi020k/og/satori'

const regular = await readFile('public/fonts/Inter-Regular.ttf')

export default defineConfig({
  cards: [{ output: 'index.webp', data: { title: 'Hello' } }],
  renderer: createSatoriRenderer({
    satori: { fonts: [{ data: regular, name: 'Inter', weight: 400 }] },
    template: ({ title }) => html`<div style="display:flex">${title}</div>`,
  }),
})

Existing functions that already return PNG, WebP, JPEG, or AVIF bytes can use createEncodedRenderer. Large collections can use defineWorkerRenderer or createSatoriWorkerRenderer with bounded automatic concurrency.

Outputs, aliases, and assets

Define one logical card and publish WebP, PNG, JPEG, AVIF, or SVG variants. Same-format aliases reuse bytes, format aliases add encoding-specific names, and named directories support multi-app repositories.

export default defineConfig({
  outputDirectory: 'public/og',
  outputDirectories: {
    docs: 'apps/docs/public',
    store: 'apps/store/public',
  },
  cards: [{
    output: 'home.webp',
    formats: ['png', 'svg'],
    aliases: [
      'og.webp',
      { directory: 'docs', output: 'social/home.webp' },
    ],
    formatAliases: { png: ['share.png'] },
    data: home,
  }],
  assets: [{
    source: 'assets/app-icon.png',
    directory: 'store',
    output: 'app-icon.png',
  }],
  renderer,
})

Deterministic preset typography

Presets bundle Inter Variable, embed it into generated SVG, measure real glyph advances, split long tokens at grapheme boundaries, and truncate safely. Text layout therefore stays portable across build machines, mixed-width scripts, code-heavy titles, and emoji.

export default definePresetConfig({
  cards,
  preset: {
    brand: { name: 'Example' },
    typography: {
      file: 'public/fonts/Brand.woff2',
      family: 'Brand',
    },
  },
})

Set preset.typography.file to a local WOFF, WOFF2, TTF, or OTF font and give it a matching family. The file is automatically included in the preset cache fingerprint. Keep the bundled font by omitting typography.

Cache and cleanup guarantees

Fingerprints include card data, dimensions, destinations, config contents, declared sources, the generator version, and an optional semantic cache key. Presets also record their preset version.

Semantic cache revisions

Set cache.key when renderer behavior changes without a directly tracked source change. The key participates in every fingerprint and appears in human-readable and JSON summaries. Preset configs supply their own preset-v1 key automatically.

export default defineConfig({
  cards,
  renderer,
  cache: {
    key: 'editorial-renderer-v2',
    sources: ['public/fonts/*.woff2', 'public/logo.svg'],
  },
})

Output and manifest paths remain constrained to the project root. Commit the manifest with committed images; ignore both when images are CI-only artifacts. Use santi-og check for verification and santi-og compare for non-destructive visual reports.

CLI reference

Machine-readable results

Add --json for CI, migration tooling, or adoption reports. Generation and checks expose the exact changed sets, total logical cards, library version, semantic cache key, and elapsed time.

{
  "command": "generate",
  "config": "/project/og.config.mjs",
  "cacheKey": "preset-v1",
  "checked": false,
  "generated": ["home.webp"],
  "skipped": ["docs.webp"],
  "cleaned": [],
  "stale": [],
  "total": 2,
  "version": "0.4.0",
  "elapsedMilliseconds": 184
}

Config reference