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 inspect http://localhost:4321 --open
pnpm exec santi-og audit --site dist --site-url https://example.com --sarif
pnpm exec santi-og audit --site dist --site-url https://example.com --standards
pnpm exec santi-og migrate --report --json
pnpm exec santi-og upgrade --to 1.0.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. Pinned remote images use verified content-addressed caching, while the typed decoration slot adds a trusted product visual without replacing the preset shell.

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, localized alternates, 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. Locale-matrix helpers reuse the same hreflang expectations in final-output audits.

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

One site contract, extensible schemas, and final-output auditing

defineSite binds metadata defaults once and derives pages, cards, HTML, Astro head output, and Next.js metadata. Route manifests connect generated cards to built routes, including the JSON-LD @type values each route requires.

import MetadataHead from '@santi020k/og/astro/head'
import { articleSchema, defineSchemaRecipe, serializeJsonLd } from '@santi020k/og/schema'
import { defineSite } from '@santi020k/og/site'

export const site = defineSite({
  siteUrl: 'https://example.com',
  siteName: 'Example',
  publicImagePath: '/og',
  defaults: { image: { width: 1200, height: 630 } },
})

export const page = site.page({
  pathname: '/guides/useful',
  title: 'A useful guide',
  description: 'One definition for metadata, card, and audit.',
  image: { output: 'guides/useful.webp', alt: 'Useful guide card' },
  schemaTypes: ['TechArticle'],
})

const jsonLd = serializeJsonLd(articleSchema({
  type: 'TechArticle',
  name: page.title,
  url: 'https://example.com/guides/useful',
}))

// Astro: <MetadataHead page={page} site={site.options} />
// Starlight: import Head from '@santi020k/og/astro/starlight'
// CI: santi-og audit --site dist --site-url https://example.com --standards

Built-in JSON-LD recipes cover websites, web pages, articles, software, events, FAQs, offers, images, breadcrumbs, collections, people, and organizations. Use extendSchema or defineSchemaRecipe for additional Schema.org vocabulary and domain-specific scenarios.

santi-og audit checks final HTML, canonicals, Open Graph and X metadata, h1 and language contracts, image bytes, dimensions and MIME declarations, duplicates, manifest coverage, and route-specific schemas. Add --standards for sitemap, robots, hreflang, and redirects; add --llms for AI-readable Markdown coverage. Reusable audit configs align local and CI policy, and human reports group repeated root causes.

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. createImageResponse wraps the same renderer for prerendered or on-demand Fetch-compatible routes.

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-v2 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-v2",
  "checked": false,
  "generated": ["home.webp"],
  "skipped": ["docs.webp"],
  "cleaned": [],
  "stale": [],
  "total": 2,
  "version": "1.0.0",
  "elapsedMilliseconds": 184
}

Config reference