Docs Social Images

---
name: docs-social-images
description: How the docs site generates per-page og:image cards, and the cache and font traps when changing them. Use when editing the OG card design, og-theme.js, or a page's social preview image.
---

# Docs social preview images

Every page's `og:image` is generated per page by `docs/src/app/api/og/route.jsx` — title,
description and section come from the page's own MDX, resolved through `lib/og-page.js`.

**Adding a page needs nothing.** The card is generated from its frontmatter automatically.

## Three traps

- **Changing the card design means bumping `OG_VERSION`** in `lib/og-theme.js`. Crawlers cache
  social images by URL; without a new `v=`, LinkedIn and Slack keep serving the old picture.
  Editing a page's own title or description needs nothing — `h=` in the URL is a hash of the card
  text, so it changes on its own.
- **Card colours are literal hex in `lib/og-theme.js`, copied from `tokens.css`.** satori never
  sees a stylesheet, so `var(--rh-*)` resolves to nothing. This is the one place hex is expected —
  change both files together. See the `docs-design-tokens` skill for the token rules everywhere
  else.
- **Fonts are TTF subsets in `docs/public/fonts/og/`**, not the woff2 the site uses: satori cannot
  decode woff2. Regenerate with `docs/scripts/generate-og-fonts.py` after a font change.

## Hand-made images

A page that needs one sets `ogImage: /path.png` in frontmatter. Use PNG or JPEG — social crawlers
do not render webp reliably.