OG Thumbnails

Explainer automatically generates Open Graph (OG) thumbnail images for every documentation page using the @explainer/thumbnail package.

How it works

The thumbnail system uses Satori to render an SVG layout and Resvg to convert it to a PNG image. Each page gets a unique thumbnail.png based on its title and description.

Two modes

Collection mode (Docs, Blog)

Scans a content directory for .mdx files and generates thumbnails for each page:

astro.config.ts
import { thumbnail } from '@explainer/thumbnail'

export default defineConfig({
  integrations: [
    thumbnail({
      appName: 'Explainer',
      content: {
        type: 'collection',
        directory: 'src/content/docs',
      },
    }),
  ],
})

Static mode (Website)

Generates thumbnails for a predefined list of pages:

astro.config.ts
thumbnail({
  appName: 'Explainer',
  content: {
    type: 'static',
    pages: [
      {
        path: '/',
        title: 'Explainer v2',
        description: 'Documentation boilerplate for developers.',
      },
    ],
  },
})

Development vs Build

Mode	Behavior
Dev	Thumbnails are generated on-the-fly when requested, with caching
Build	All thumbnails are batch-generated during the `astro:build:done` hook

Customizing the primary color

You can customize the accent color used in the thumbnail background:

thumbnail({
  appName: 'Explainer',
  primaryColor: '#7c3aed',
  content: { ... },
})

The color is resolved using culori and supports RGB, hex, and oklch formats. The default color is oklch(0.707 0.217 293).

Output

Generated thumbnails are 960×540 px PNG images placed alongside each page’s output directory. They are automatically referenced in the page’s <meta> tags for social media previews.