Add custom og:images#4860
Open
Duncanma wants to merge 3 commits into
Open
Conversation
…ating og images in package.json. Update yarn.lock.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📖 Docs PR preview linksThis PR does not change any pages in /docs. If you make updates, links to the modified pages will appear here. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Automatically generate social share (og:image) cards for every doc page
Problem
Every page on docs.temporal.io currently shares a single static
og:image(themeConfig.imageindocusaurus.config.js) — so a link to any page, whether the homepage or a deep SDK reference page, unfurls in Slack/X/LinkedIn with the exact same generic card. There's no way to give a page a more relevant preview without hand-making an image.That image, below, is also huge (5.6MB)
What this does
Adds a build-time Docusaurus plugin (
plugins/og-image/) that generates a unique, on-brand social share card for every doc page automatically — no authoring work required. Each page will get an image like thisThese images will show up on Slack, Bluesky, X, etc.
**Before in slack (note the 6MB in the preview, that's Slack pointing out how large the preview image is)
After
How a card is built
Each card is 1200×630 and includes:
develop/go/...→ Go SDK,cloud/...→ Cloud)title, falling back to the first#heading, falling back to a humanized filename)docs.temporal.ioRendered with Satori +
@resvg/resvg-js, then re-encoded throughsharpas a palette-quantized PNG — cuts output size by ~88% (232.7KB → 28.9KB per card) with no visible quality loss, since the raw resvg PNG output has no compression options and the gradient background otherwise compresses poorly.Manual overrides
Any page can opt out of the generated card:
image:field (existing Docusaurus mechanism), or<Head>component with its ownog:image/twitter:imagemeta tags, for cases that need more controlThe plugin detects either and leaves the page untouched. See the new "Social share images (og:image)" section in
CONTRIBUTING.mdfor authoring instructions.Caching
Generated images are cached by content hash (
node_modules/.cache/og-images/) — nested undernode_modulesso it's gitignored for free and rides along with whatever already cachesnode_modulesin CI/Vercel between builds. A page's card only regenerates when its title, description, section, or the template itself changes.Performance
Measured across all ~625 doc pages:
yarn.lockchange): ~86s to render every card fresh (~106ms/card)bin/check-og-build-budget.js(yarn check:og-budget) asserts these stay within budget on every build, so a future regression (e.g. a design change that balloons per-card size) gets caught rather than quietly shipped.Testing
plugins/og-image/index.test.js— unit tests (yarn test) for the override-detection logic against synthetic input, no real build requiredbin/validate-og-images.js(yarn validate:og-images) — confirms after a real build that every doc page has a correct generated image, override pages (if any) kept their own image, and every page the plugin doesn't touch (404, search, changelog, tag pages, etc.) still falls back to the site defaultbin/generate-og-gallery.js— dev-only tool that renders a browsable grid of every generated card for visual reviewCloses #4858
┆Attachments: EDU-6690 Add custom og:images