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.
Installs into .claude/skills of the current project.
Are you the author of Docs Social Images?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/rhesis-ai-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.
