# Custom OG Images

Generate a branded Open Graph social share image using your site's theme colors, brand identity, and custom content. The `/og-image` skill walks you through the process — describe what you want, and the agent writes a script to generate a 2400×1260 PNG (2x retina) saved to `media/og-image.png`.

## How to use it

Type `/og-image` in Claude Code (or any MCP-connected agent). The skill:

1. Reads your site config — brand name, description, theme mode, accent color
2. Asks which theme to use for the image (if your theme is set to `system`)
3. Asks three questions: heading text, subheading text, and what the main visual should be
4. Writes and runs a Node script that generates the image using [Satori](https://github.com/vercel/satori+newtab) and [Resvg](https://github.com/nicolo-ribaudo/resvg-js+newtab)
5. Updates `settings/seo.md` automatically
6. Points you to the raw PNG for review — iterate without restarting the dev server

## What you can ask for

There are no fixed layouts. The agent designs whatever you describe. Some examples:

- A clean card with your brand name, tagline, and accent bar
- A browser chrome mockup showing your site's homepage
- A split-pane view with a code editor and rendered output
- Your logo centered on a gradient background
- A feature grid with icons and labels
- Anything you can describe — the agent builds it with Satori elements

The third question ("What should the main visual be?") is where you describe this. If you skip it, the agent falls back to a simple heading + subheading layout with your brand image.

## How colors are resolved

The agent reads CSS variables directly from your `theme/styles.css` file for the chosen theme mode. Ten color values are extracted:

| Variable | Used for |
|---|---|
| `--color-bg` | Image background |
| `--color-bg-secondary` | Secondary surfaces |
| `--color-bg-tertiary` | Tertiary surfaces |
| `--color-text` | Heading text |
| `--color-text-secondary` | Subheading text |
| `--color-text-tertiary` | Muted elements |
| `--color-border` | Borders and separators |
| `--color-accent` | Accent highlights |
| `--color-code-bg` | Code block backgrounds |
| `--color-code-text` | Code block text |

Any customizations you've made in `settings/theme.md` are reflected in `theme/styles.css` via [Live Build Sync](/docs/live-build-sync), so the OG image always matches your current theme.

## What happens to settings

When the image is generated, `settings/seo.md` is updated:

```yaml
---
ogImage: /media/og-image.png
---
```

Every page without a custom `image` in frontmatter uses this image. To revert to auto-generated cards, change it back to `ogImage: auto`.

## How it works under the hood

The skill instructs the agent to write a standalone Node script that:

1. Loads Inter fonts from `sitemd/engine/seo/fonts/`
2. Builds a layout using Satori's element format (flexbox-based, no DOM)
3. Renders the layout to SVG via Satori at 1200×630
4. Converts SVG to PNG at 2x resolution (2400×1260) via Resvg
5. Saves the result to `media/og-image.png`

The script is deleted after successful generation. On each iteration, the agent modifies and re-runs it.

## Iterating

After the first generation, ask your agent for changes — different text, a different visual, adjusted colors. The agent updates the script and overwrites `media/og-image.png`. Open the raw file to see each iteration immediately. The dev server does not need to be restarted between iterations, but you do need to relaunch it to see the updated image in [SEO Preview](/docs/seo-preview).

## Per-page images

This feature generates a single site-wide OG image. For per-page custom images, add `image: /path/to/image.png` to that page's frontmatter — see [SEO — Custom OG images](/docs/seo#custom-og-images).

## Dependencies

The same packages required for [OG image generation](/docs/seo#og-image-generation):

```bash
npm install sharp satori @resvg/resvg-js
```

These are already installed if you have auto-generated OG images enabled.

## Related

- [SEO](/docs/seo) — full SEO configuration including auto-generated OG cards
- [SEO Preview](/docs/seo-preview) — preview social cards on the dev server
- [Agent Skills](/docs/skills) — all skills that ship with sitemd
- [Themes](/docs/themes) — customize the colors used by the generator