OG 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.astro already emits og: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
.jpg trips 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 a default.jpg. Run it with npm run og. Idempotent; commit the output.
src/layouts/Base.astro — image prop defaults to /images/og/default.jpg. A page
gets its own card by passing image="/images/og/<slug>.jpg"; a page with no image= falls
back to the default — which only exempt utility pages should do (the test below enforces
it). og:image + twitter:image are derived from that one prop.
tests/seo.spec.ts — for every page, reads the referenced card off disk and asserts
it exists in public/, 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 an OWN_CARD_EXEMPT allowlist (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
BRAND block in scripts/generate_og_cards.py — BRAND_NAME,
SITE_URL_LABEL, the background/accent/text colours (copy the hexes from
src/styles/global.css / BRAND.md), and optionally point LOGO at 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
PAGES block — one (slug, title, [subtitle, …]) per
content page. Then set image="/images/og/<slug>.jpg" on that page's <Base>. Only
exempt utility pages (home, privacy, …) may fall back to default.jpg; every other
content page must be listed here and wired to its own card, or seo.spec.ts fails it.
- Run
npm run og, then npm 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:image at a remote/CDN URL the repo can't verify. Keep cards on-site
in public/ so seo.spec.ts can prove they exist and fit.
1---2name: og-images3description: >4 Generate branded per-page Open Graph (social share) cards for a website: a 1200×6305 JPEG ≤300 KB for every page, rendered by a committed Python+Pillow script and wired6 so each page sets its own `image=` (with a default fallback) and the test suite proves7 the card exists at the right size. Use when building or auditing a site's share previews —8 "OG image", "og:image", "social share image", "share card", "WhatsApp/Slack/LinkedIn9 preview", "Twitter card image", "the picture when I share the link", "per-page OG images",10 "generate share images". For general marketing image creation/optimization use the11 `image` skill; this one is specifically the build-time, tested, per-page card generator12 for the suite's Astro starter.13metadata:14 source: https://skillmd.com/skills/karero/og-images15 version: 1.0.016---1718# OG images — per-page share cards1920When a URL is shared (WhatsApp, Slack, iMessage, X, LinkedIn, Discord), the `og:image`21is the preview. Get it wrong and the link shares with **no picture** or a badly cropped22one — a silent conversion leak. This skill makes every page render a consistent,23on-brand **1200×630 JPEG ≤300 KB**, generated by a committed script and enforced by the24test gate.2526## The three hard rules (messengers enforce them)27281. **1200×630, exactly** (1.91:1). Square images get cropped on X/Teams; off-ratio ones29 letterbox. The starter's `Base.astro` already emits `og:image:width/height` = 1200×630.302. **≤300 KB.** WhatsApp silently **drops** previews heavier than ~300 KB — the link then31 shares with no image at all. Encode JPEG and compress to fit.323. **Extension matches the bytes.** A PNG renamed `.jpg` trips strict scrapers. Use JPEG33 for photographic cards, PNG only for flat logo/gradient cards that still come ≤300 KB.3435## How it's wired in the Astro starter3637- **`scripts/generate_og_cards.py`** — the generator. Renders one card per page you list,38 plus a `default.jpg`. Run it with **`npm run og`**. Idempotent; commit the output.39- **`src/layouts/Base.astro`** — `image` prop defaults to `/images/og/default.jpg`. A page40 gets its own card by passing `image="/images/og/<slug>.jpg"`; a page with no `image=` falls41 back to the default — which only **exempt utility pages** should do (the test below enforces42 it). `og:image` + `twitter:image` are derived from that one prop.43- **`tests/seo.spec.ts`** — for every page, reads the referenced card off disk and asserts44 it exists in `public/`, is ≤300 KB, a real JPEG/PNG, and exactly 1200×630. It also enforces45 that every page has its **own** card (not the generic default) and that no two pages share46 one — except an `OWN_CARD_EXEMPT` allowlist (home + utility pages, default `['/', '/privacy']`).47 Opt-out: as you add content pages, leave them OUT of the allowlist and the guard flags any48 that forgot a card. A missing/oversized/shared card **fails the build** — OG cards can't49 silently rot, and a new page can't silently ship on the generic default.5051The starter ships a generated `public/images/og/default.jpg` so the suite is green from52commit 1; you replace it with your brand by editing the script and re-running `npm run og`.5354## Setup for a site (two edits, one command)55561. **Fill the `BRAND` block** in `scripts/generate_og_cards.py` — `BRAND_NAME`,57 `SITE_URL_LABEL`, the background/accent/text colours (copy the hexes from58 `src/styles/global.css` / `BRAND.md`), and optionally point `LOGO` at a transparent59 **raster** PNG for a faint emblem watermark (SVG won't load — Pillow needs raster).60 The card is a **dark** share card by design: light text on a deep background reads well61 in every chat app regardless of whether the site theme is light or dark.622. **List per-page cards** in the `PAGES` block — one `(slug, title, [subtitle, …])` per63 content page. Then set `image="/images/og/<slug>.jpg"` on that page's `<Base>`. Only64 **exempt utility pages** (home, privacy, …) may fall back to `default.jpg`; every other65 content page must be listed here and wired to its own card, or `seo.spec.ts` fails it.663. **Run `npm run og`**, then `npm test`. Commit the generated JPEGs.6768`npm run og -- --check` exits non-zero if any card exceeds 300 KB — wire it into CI or the69pre-push hook if you want generation (not just validation) gated.7071## Long or unbreakable words (German compounds)7273`fit_title()` shrinks the font until every wrapped line actually fits the card's text74area, not just until the line count looks right. Three overflow cases fail the run75loudly (`OG card OVERFLOW: ...`) instead of drawing past the edge, all unconditional76(not gated behind `--check`, which only guards file size):77- a single unbroken word wider than the text area at the smallest size (52pt) — long78 German compounds (`Suchmaschinenoptimierung`, `Datenschutz-Grundverordnung`) are the79 classic trigger;80- a title still needing more than 3 lines at 52pt (it would collide with the81 subtitles/footer);82- a subtitle wider than the text area (subtitles render at a fixed 30pt).8384If you hit one: shorten the text to a near-synonym, or insert a plain space at a85natural compound boundary (`Suchmaschinen Optimierung`) — the generator deliberately86does not hyphenate compounds automatically.8788## Prerequisite8990Pillow, a local authoring dependency only (not shipped to the site or its runtime):9192```bash93pip3 install Pillow94```9596On **Windows**, run authoring/build inside **WSL2** — the suite's recommended Windows97environment (`SETUP.md`), where `python3` and the bash helpers all work. Running natively98is fine too: `py -m pip install Pillow`, and `npm run og` already falls back `python3 → py99-3 → python`.100101## Going further — photo-driven cards102103The generator deliberately ships the **text-card** core (emblem + wordmark + accent bar +104title + subtitles + footer URL) because it works for any site with zero per-page art. When105a content type has a natural image — a speaker headshot, a product shot, an author avatar —106extend `build_page()` to read that image from frontmatter and composite a circular portrait107+ glow beside the text: iterate a content collection (`src/content/<type>/*.md`), render one108portrait card per entry alongside the static-page cards, and keep the same encode-under-300 KB109step. The template ships the text-card core; the portrait variant is a small, additive change.110111## Don't112113- **Don't hand-export cards in Figma/Canva per page.** They drift and balloon past 300 KB.114 The script is the single source of truth; re-running it is free.115- **Don't ship a square logo as `og:image`.** It crops badly. Always 1200×630.116- **Don't point `og:image` at a remote/CDN URL the repo can't verify.** Keep cards on-site117 in `public/` so `seo.spec.ts` can prove they exist and fit.