og-images
Generate branded per-page Open Graph (social share) cards for a website: a 1200×630 JPEG ≤300 KB for every page, rendered by a committed Python+Pillow script and wired so each page sets its own `image
SKILL.mdskills/og-images/SKILL.md
GitHubOG images — per-page share cards
When a URL is shared (WhatsApp, Slack, iMessage, X, LinkedIn, Discord), the og:image
is the preview. Get it wrong and the link shares with no picture or a badly cropped
one — a silent conversion leak. This skill makes every page render a consistent,
on-brand 1200×630 JPEG ≤300 KB, generated by a committed script and enforced by the
test gate.
The three hard rules (messengers enforce them)
- 1200×630, exactly (1.91:1). Square images get cropped on X/Teams; off-ratio ones
letterbox. The starter's
Base.astroalready emitsog:image:width/height= 1200×630. - ≤300 KB. WhatsApp silently drops previews heavier than ~300 KB — the link then shares with no image at all. Encode JPEG and compress to fit.
- Extension matches the bytes. A PNG renamed
.jpgtrips strict scrapers. Use JPEG for photographic cards, PNG only for flat logo/gradient cards that still come ≤300 KB.
How it's wired in the Astro starter
scripts/generate_og_cards.py— the generator. Renders one card per page you list, plus adefault.jpg. Run it withnpm run og. Idempotent; commit the output.src/layouts/Base.astro—imageprop defaults to/images/og/default.jpg. A page gets its own card by passingimage="/images/og/<slug>.jpg"; a page with noimage=falls back to the default — which only exempt utility pages should do (the test below enforces it).og:image+twitter:imageare derived from that one prop.tests/seo.spec.ts— for every page, reads the referenced card off disk and asserts it exists inpublic/, is ≤300 KB, a real JPEG/PNG, and exactly 1200×630. It also enforces that every page has its own card (not the generic default) and that no two pages share one — except anOWN_CARD_EXEMPTallowlist (home + utility pages, default['/', '/privacy']). Opt-out: as you add content pages, leave them OUT of the allowlist and the guard flags any that forgot a card. A missing/oversized/shared card fails the build — OG cards can't silently rot, and a new page can't silently ship on the generic default.
The starter ships a generated public/images/og/default.jpg so the suite is green from
commit 1; you replace it with your brand by editing the script and re-running npm run og.
Setup for a site (two edits, one command)
- Fill the
BRANDblock inscripts/generate_og_cards.py—BRAND_NAME,SITE_URL_LABEL, the background/accent/text colours (copy the hexes fromsrc/styles/global.css/BRAND.md), and optionally pointLOGOat a transparent raster PNG for a faint emblem watermark (SVG won't load — Pillow needs raster). The card is a dark share card by design: light text on a deep background reads well in every chat app regardless of whether the site theme is light or dark. - List per-page cards in the
PAGESblock — one(slug, title, [subtitle, …])per content page. Then setimage="/images/og/<slug>.jpg"on that page's<Base>. Only exempt utility pages (home, privacy, …) may fall back todefault.jpg; every other content page must be listed here and wired to its own card, orseo.spec.tsfails it. - Run
npm run og, thennpm test. Commit the generated JPEGs.
npm run og -- --check exits non-zero if any card exceeds 300 KB — wire it into CI or the
pre-push hook if you want generation (not just validation) gated.
Long or unbreakable words (German compounds)
fit_title() shrinks the font until every wrapped line actually fits the card's text
area, not just until the line count looks right. Three overflow cases fail the run
loudly (OG card OVERFLOW: ...) instead of drawing past the edge, all unconditional
(not gated behind --check, which only guards file size):
- a single unbroken word wider than the text area at the smallest size (52pt) — long
German compounds (
Suchmaschinenoptimierung,Datenschutz-Grundverordnung) are the classic trigger; - a title still needing more than 3 lines at 52pt (it would collide with the subtitles/footer);
- a subtitle wider than the text area (subtitles render at a fixed 30pt).
If you hit one: shorten the text to a near-synonym, or insert a plain space at a
natural compound boundary (Suchmaschinen Optimierung) — the generator deliberately
does not hyphenate compounds automatically.
Prerequisite
Pillow, a local authoring dependency only (not shipped to the site or its runtime):
pip3 install Pillow
On Windows, run authoring/build inside WSL2 — the suite's recommended Windows
environment (SETUP.md), where python3 and the bash helpers all work. Running natively
is fine too: py -m pip install Pillow, and npm run og already falls back python3 → py -3 → python.
Going further — photo-driven cards
The generator deliberately ships the text-card core (emblem + wordmark + accent bar +
title + subtitles + footer URL) because it works for any site with zero per-page art. When
a content type has a natural image — a speaker headshot, a product shot, an author avatar —
extend build_page() to read that image from frontmatter and composite a circular portrait
- glow beside the text: iterate a content collection (
src/content/<type>/*.md), render one portrait card per entry alongside the static-page cards, and keep the same encode-under-300 KB step. The template ships the text-card core; the portrait variant is a small, additive change.
Don't
- Don't hand-export cards in Figma/Canva per page. They drift and balloon past 300 KB. The script is the single source of truth; re-running it is free.
- Don't ship a square logo as
og:image. It crops badly. Always 1200×630. - Don't point
og:imageat a remote/CDN URL the repo can't verify. Keep cards on-site inpublic/soseo.spec.tscan prove they exist and fit.