Per-article Open Graph cards in Astro with Satori — CJK fonts and X's title overlay

Generating a 1200x630 Open Graph card per article and locale at build time in Astro with Satori and resvg, with Japanese and Chinese fonts kept legible.

The Open Graph protocol logo, a dark grey hexagon holding a blue globe with a node on each side, beside the dark grey Open Graph wordmark on a white card
On this page

Introduction

I saw a Qiita article shared on X, and its preview card had Qiita’s logo and the article’s title drawn into the picture. Links to this blog showed only a cover image, which looked plain beside it.

Covers here come from a shared registry keyed by topic, so every Astro article unfurled as the same black Astro logo. When I built that registry I decided the cover could serve as the Open Graph image directly, and wrote that I had budgeted for Satori and didn’t need it.

Every article now gets its own 1200×630 card in each of its three languages, drawn at build time by Satori and resvg: the title, the site’s seal, and the topic cover kept as a small tile. A shared link now says which article it is, and the card is redrawn on the next build whenever the title or cover changes.

A post on X linking to an article on this blog. The card shows the seal and site name, the Astro cover as a tile, and the article title and subtitle in large type; X's dark title strip runs along the empty bottom of the card

The finished card on X. X’s own title strip sits in the band the card leaves empty.

What other sites put in og:image

og:image is the Open Graph meta tag naming the picture a crawler shows when a link is shared. Sites whose posts mostly have no image of their own generate a card with the title on it, and sites where every post has a cover use that cover. I asked Claude Code how other sites decide.

These sites generate the card, each in its own way.

GitHub built a service for this because most people never uploaded a custom image for their repository. It fills an HTML template with the repository’s name, description, owner avatar and counts, and screenshots it with Puppeteer.

GitHub's card for the repository oharu121/cli-ascii-logo: the repository name in large type, its description, the owner's avatar, and counts for contributors, issues, stars and forks

GitHub’s card for one of my repositories.

Zenn’s card shows the title, the author’s avatar and name, and the Zenn logo. Its og:image is a Cloudinary URL whose parameters lay the title over a fixed background as a text layer.

Zenn's card for a Japanese article: the title on a white card over a blue-to-purple gradient, the author's avatar and name at the bottom left, and the Zenn logo at the bottom right

Zenn’s card for an article I posted there.

Qiita’s card puts its logo above the title and the author’s avatar and handle below it. Its og:image is an imgix URL that composites a background, the avatar and the title text the same way.

Qiita's card for the same Japanese article: the Qiita logo at the top, the title in three lines with only 証 on the third, and the author's avatar and handle below

The same article on Qiita. Its card wraps 検証 across two lines.

Zenn and Qiita hand the drawing to a third-party image service, Cloudinary and imgix respectively. Such a service composes an image on request from the parameters in its URL and serves the result from its own CDN.

On note, for example, where every post has a cover, the image an author uploads for a post becomes its Open Graph image unchanged.

Why this blog shares one cover per topic

This blog’s posts have no art of their own, yet it used the cover as the Open Graph image the way note does.

I never designed an image per article. Every article on a topic shares one cover, partly so the article list shows each article’s topic at a glance, and partly because a different cover style on every post would look cluttered.

Shared on social media, though, that cover says nothing about which of my articles the link is. Here is the same pnpm article unfurled in Slack, before and after:

A Slack link preview for a pnpm 12 article: the title and description as text, then the shared pnpm logo cover as the image

Before: the image is the pnpm cover, which every pnpm article on the site also uses.

The same Slack preview with the generated card: the site's seal and name, the pnpm cover as a small tile, and the article title and subtitle set in large type

After: the generated card carries the title, so the image identifies the article on its own.

Slack prints og:title above the image, so on Slack the title now appears twice, which I think is acceptable.

The card: title, seal, and the topic image as a tile

The card keeps the cover as a small tile in the top-right corner. Every article already has a cover, so I put the title and the cover tile on the same card.

Each cover is a 1200×630 landscape logo card. The left side already carries the blog’s own seal and name, so I shrank the whole cover to 320×168 and put it on the right as a topic badge.

Anatomy of the generated Open Graph cardA 1200 by 630 card drawn to scale. A thin vermilion bar runs across the top. The seal and site name sit top left, and the cover tile, 320 by 168, sits top right. Below them the title block starts at y=272 and the subtitle block follows, together filling the 232 pixels down to a dashed safe line at y=504. The band below that line, the bottom fifth, is shaded and marked as where X prints og:title.12px bar桜oharu tech blogcover tile320×168title 80–48pxsubtitle 30px,2 lines reservedsafe line y=504X prints og:title here232pxfor text
The title block gets whatever height is left between the tile and the line X’s title strip starts at.

The rest of the layout follows from where X puts its own text. X prints og:title across the bottom of a large link card, the dark strip in the X screenshot at the top of this article.

So nothing on the card may end below 504px, the top of the bottom fifth, and the title takes the space between the tile and that line.

Titles on this blog mostly follow the pattern Main — subtitle. The card splits at the dash: the main title sets large and bold, from 80px down to 48px, and the subtitle sets at 30px in a muted grey. A 12px vermilion bar across the top matches the seal in the blog’s logo.

Three generated cards stacked: an English title about Astro link icons with the Astro tile, a Japanese title about GROUP BY ROLLUP with the LLM tile, and a Traditional Chinese title about a Claude Code logo skill with the LLM tile

One card per language. The zh-TW card is set in Noto Sans TC, the other two in Noto Sans JP, which covers Latin as well.

One prerendered endpoint per locale

Each card is written during pnpm build by an Astro endpoint, a .png.ts route. Astro calls its GET once and saves the returned PNG as a static file, which is what X and other sites fetch when they ask for the card.

The card route and the article page take their list of articles from the same function, getArticlePaths, so every published article gets exactly one card and a draft gets neither.

One article list feeds both the page and the cardOn the left, getArticlePaths(locale) returns every published article in one language. Two arrows leave it: one to the route blog/[slug].astro, which outputs the article page as HTML, and one to the route og/[slug].png.ts, which outputs the Open Graph card as PNG. A strip at the bottom says the same runs once each for en, ja and zh-tw.getArticlePaths(locale)every published articlein one languageblog/[slug].astroog/[slug].png.tsarticle pageHTMLOpen Graph cardPNGThe same runs once each for en, ja and zh-tw
One list of articles feeds both routes, once per language.

Each locale gets a one-line wrapper:

src/pages/ja/og/[slug].png.ts
import type { APIContext } from "astro";
import { ogCardPaths, ogCardResponse } from "@/lib/og-card";


export const getStaticPaths = () => ogCardPaths("ja");
export const GET = (context: APIContext) => ogCardResponse("ja", context);

The card is drawn by one module, src/lib/og-card.ts, in two steps:

  1. Satori lays it out. Satori is an open-source library from Vercel that turns a layout described in JSX and CSS into SVG. No React is needed: the layout is written directly as plain { type, props } objects and handed to Satori.
  2. resvg turns it into a PNG. @resvg/resvg-js rasterises Satori’s SVG into a PNG, because X accepts JPG, PNG, WEBP and GIF for og:image but not SVG.
src/lib/og-card.ts
const tree = el("div", { width: 1200, height: 630, display: "flex", flexDirection: "column", padding: 64 }, [
  el("div", { display: "flex", justifyContent: "space-between" }, [
    sealAndSiteName,
    { type: "img", props: { src: tileDataUri, width: 320, height: 168 } },
  ]),
  el("div", { fontSize: size, fontWeight: 700, lineClamp: maxLines }, title),
  el("div", { fontSize: 30, color: "#475569", lineClamp: 2 }, subtitle),
]);
const svg = await satori(tree, { width: 1200, height: 630, fonts });
const png = new Resvg(svg).render().asPng();

Satori, resvg and the fonts are devDependencies, used only at build time, so none of them is bundled into the serverless function the site deploys beside its static files. Each card took about 25ms in the build log.

For each card, og-card.ts does these steps in order:

  1. Split the title at — into a main title and a subtitle.
  2. Pick the title size from its length and the height left.
  3. Glue Japanese and Chinese words together with Intl.Segmenter, so no word breaks in the middle.
  4. Load only the font subsets the card’s text needs, each under its own name.
  5. Shrink the cover into a tile with sharp, and build the { type, props } layout with the title and seal.
  6. Hand the layout to Satori for an SVG, then to resvg for a PNG.
src/lib/og-card.ts
async function renderOgCard(entry: BlogEntry, locale: Locale): Promise<Buffer> {
  const { title, thumbnail } = entry.data;
  // 1. Split "Main — subtitle"
  const [rawMain, ...rest] = title.split(/\s+—\s+/);
  const rawSub = rest.length ? rest.join(" — ") : undefined;
  // 2. Pick the title size
  const { size, maxLines } = fitTitle(rawMain, rawSub, locale);
  // 3. Glue CJK words
  const main = glue(rawMain, locale);
  const sub = rawSub && glue(rawSub, locale);
  // 4. Load only the subsets the text needs
  const fonts = [...fontsFor(locale, 700, main + brand + "…" + WJ) /* … */];
  // 5. Build the layout, cover tile included
  const tree = el("div", { /* … */ }, [/* seal, await thumbnailTile(thumbnail), main, sub */]);
  // 6. Lay out to SVG, then rasterise to PNG
  const svg = await satori(tree, { width: W, height: H, fonts });
  return new Resvg(svg, { fitTo: { mode: "width", value: W } }).render().asPng();
}

Steps 3 and 4 are the two traps below; step 2 is the last section.

The cover tile is read straight from src/assets/thumbnails/<key>.png or .webp, using the registry key such as astro-generic. sharp resizes it to 320×168 and converts it to PNG before it goes to Satori.

Finally, the article layout points og:image at the card instead of at a resized cover:

src/layouts/ArticleLayout.astro
const ogAsset = await getImage({ src: cover.src, width: 1200, height: 630, format: "png" });
const ogImage = new URL(ogAsset.src, Astro.site).href;
const ogImage = new URL(localeUrl(locale, `/og/${slug}.png`), Astro.site).href;

Two traps between Satori and a trilingual title

Both showed up on real titles from this blog, and each one renders without an error.

Trap 1: Satori draws tofu on the Open Graph card

Satori loads one font file per family name, so a font split across many files has to be registered under many names. Satori can only draw characters it has been given a font for, and no system font fills in at build time. A character with no matching font is drawn as an empty box, known as tofu.

I took the fonts from Fontsource packages, @fontsource/noto-sans-jp and @fontsource/noto-sans-tc. Fontsource publishes Google Fonts and other open-source fonts as npm packages, so no font binaries enter the repository and the build fetches nothing. Noto Sans TC is there because Noto Sans JP lacks Chinese forms such as 查 and 夠, which Japanese writes differently or not at all.

Fontsource splits each weight into subsets by unicode-range, the range of characters each file covers: about 125 files for Noto Sans JP Bold, each shipped as both WOFF and WOFF2. Satori reads TTF, OTF and WOFF but not WOFF2.

The WOFF files come to about 5.2MB per weight, too much to load for every card, so og-card.ts reads each weight’s CSS and passes Satori only the subsets whose range covers the card’s text.

From Fontsource subsets to the fonts Satori receivesOn the left, Fontsource splits Noto Sans JP Bold into about 125 subset files by unicode-range, such as Latin, kana and two blocks of kanji. Each file comes as WOFF and WOFF2, and the WOFF2 copies are struck out. In the middle, og-card.ts keeps only the subsets whose range covers the card’s text and gives each file its own family name. On the right, Satori receives three named files out of about 125. The kanji part 1 subset, which the title does not need, is dimmed.FontsourceNoto Sans JP BoldLatinWOFF2WOFFKanaWOFF2WOFFKanji, part 1WOFF2WOFFKanji, part 2WOFF2WOFF… about 125 filesog-card.ts1. keep subsets whoserange covers the text2. give each fileits own family nameSatoriNoto Sans JP · LatinNoto Sans JP · KanaNoto Sans JP · Kanji 23 of about 125 filesWOFF2 is skipped: Satori reads only TTF, OTF and WOFF
Only the subsets the card’s text needs reach Satori, each under its own name.

Registering those subsets under the family name they share, Noto Sans JP, rendered this:

A generated card for a Japanese title where almost every character in the brand name, title and subtitle is drawn as an empty box, with only a few kanji rendered

Only the few characters that happened to sit in the subset Satori kept are drawn.

Giving each subset its own name and listing every name in fontFamily fixes it, because Satori does fall back glyph by glyph across a family stack:

src/lib/og-card.ts
return faces(pkg, family, weight)
  .filter(({ ranges }) => cps.some((cp) => ranges.some(([a, b]) => cp >= a && cp <= b)))
  .map(({ family, file }) => {
    let data = fileCache.get(file);
    if (!data) fileCache.set(file, (data = readFileSync(file)));
    return { name: `${family} ${file}`, weight, style: "normal", data };
  });

Finally, the card’s outermost element gets every one of those names, quoted and comma-separated, as its fontFamily:

src/lib/og-card.ts
const stack = [...new Set(fonts.map((f) => `"${f.name}"`))].join(", ");
// → "Noto Sans JP …/noto-sans-jp-0-700-normal.woff", "Noto Sans JP …/noto-sans-jp-latin-700-normal.woff", …


const tree = el("div", { /* … */ fontFamily: stack }, [/* … */]);

Trap 2: Satori breaks Japanese and Chinese words anywhere

Satori treats every gap between two CJK characters as a line-break opportunity, because it has no dictionary of Japanese or Chinese words. Qiita’s card splitting 検証 across two lines, shown earlier, is the same problem. The zh-TW title below wraps inside 五次, “five times”, leaving 五 at the end of one line and 次 at the start of the next:

A generated card for a Traditional Chinese title whose first line ends on the character 五 and whose second line begins with 次, splitting the word 五次

The break falls between 五 and 次, inside one word.

Intl.Segmenter, built into browsers and Node.js, does carry dictionaries for both languages when given granularity: "word". og-card.ts segments the title, and inside each CJK word it puts U+2060 WORD JOINER between the characters, an invisible character that forbids a break at its position:

src/lib/og-card.ts
const CJK = /[\u3040-\u30ff\u3400-\u9fff\uf900-\ufaff]/;
const WJ = "\u2060";


function glue(text: string, locale: Locale): string {
  const seg = new Intl.Segmenter(FONT_PKG[locale].segmenter, { granularity: "word" });
  return [...seg.segment(text)]
    .map(({ segment }) => (CJK.test(segment) ? [...segment].join(WJ) : segment))
    .join("");
}

The same title now breaks at 是從 / 五次走錯路, between words. The joiner is a character too, so it has to be in the text the font subsets are chosen for; otherwise no font covers it and it renders as a box.

Sizing the title by the height left above the safe line

The title size is chosen from the height left above the safe line at 504px. A bigger font wraps onto more lines, so what has to fit is the total height, lines times size.

The title block starts at 272px, under the 12px bar, the 64px padding, the 168px tile and a 28px gap, so it has 232px to the safe line. The subtitle’s share comes off first, then og-card.ts takes the largest of 80, 72, 64, 56 and 48px whose estimated height fits what is left:

src/lib/og-card.ts
function fitTitle(main: string, sub: string | undefined, locale: Locale) {
  const subH = sub ? SUB_GAP + 2 * SUB_SIZE * SUB_LH : 0;
  const budget = SAFE_BOTTOM - TEXT_TOP - subH;
  const widest = longestWord(main, locale);
  const size =
    [80, 72, 64, 56, 48].find(
      (s) => lines(main, s) * s * lineHeight(s) <= budget && widest * s * 0.5 <= LINE_W,
    ) ?? 48;
  const maxLines = Math.max(1, Math.floor(budget / (size * lineHeight(size))));
  return { size, maxLines };
}

The subtitle’s share is always two lines, because its lineClamp (the most lines shown, with an ellipsis past that) is 2. A subtitle that wraps to two lines when one was expected still fits.

The title has its own cap too: fitTitle works out maxLines, the number of lines the remaining space can hold, and sets it as the title’s lineClamp. So a wrong estimate ends in an ellipsis rather than in the overlay.

The lowest text on any card the site now builds, title or subtitle, sits at y=488, still above the safe line.

The widest check handles the word joiner’s side effect: a glued word cannot break, so a long katakana compound at 80px would run off the right edge. The size steps down until the longest word fits on one line.

Summary

Covers on this blog are shared by topic, so they say what an article is about but not which article it is. An Open Graph card exists for sharing on social media, a different job from a cover.

Every article now gets a generated card: the cover shrinks to a tile in the top-right corner and the title is written on the card, so a shared link shows which article it is.

At build time, a prerendered endpoint per language prepares each card’s layout and hands it to Satori and resvg. Japanese and Chinese titles need two things Satori does not do on its own: a separate font name per Fontsource subset, and word joiners from Intl.Segmenter to keep words whole.

The title size, separately, comes from the height left above X’s title strip.

References

Share this article

More

More