docs(fumadocs): document build-time site OG image generation

[tembo]

Summary

Following PR #155, which moved the site-wide social card (public/og/email-sdk.png) to a fully code-drawn composition, the apps/fumadocs README documented the runtime blog OG images (/og/blog/*) but had no coverage of the new build-time site OG image subsystem. This PR closes that gap.

Adds a Site OG image section to apps/fumadocs/README.md covering the generator introduced/reworked in #155:

• What it is & where it's used — the default og:image/twitter:image for every page (siteOgImageUrl in src/lib/shared.ts, wired in src/lib/metadata.ts) and the blog-route fallback (src/routes/blog/$slug.tsx), explicitly distinguished from the runtime /og/blog/* images.
• What keeps it current — a table mapping the two build-time-derived values to their single sources of truth: the adapter count from packages/email-sdk/package.json exports, and the sponsor row from src/lib/sponsors.ts (shared with the SponsorSpotlight component).
• Regenerating — bun run og:generate, its place in the build script, committing the PNG, and the VITE_OG_IMAGE_VERSION cache-buster.
• Deterministic rendering — bundled Liberation fonts + loadSystemFonts: false.
• Layout guardrails — the build throws on provider-grid / sponsor-row overflow rather than drawing off-layout chips.
• Common changes — step-by-step for adding a sponsor or a provider-grid logo.

Codepaths covered

• apps/fumadocs/scripts/og/generate-og-image.ts (generator, overflow guards, deterministic font setup)
• apps/fumadocs/src/lib/sponsors.ts (sponsor source of truth) and src/components/sponsors.tsx (shared consumer)
• apps/fumadocs/src/lib/shared.ts + src/lib/metadata.ts (where the card is used as OG/Twitter image)
• apps/fumadocs/src/routes/blog/$slug.tsx (fallback image)
• packages/email-sdk/package.json exports (adapter-count derivation)
• apps/fumadocs/package.json build / og:generate scripts

Key knowledge gaps addressed

• How the OG card avoids going stale (both values derived at build time — the old art claimed 18 providers vs. 23 today).
• How to add a sponsor or provider logo without breaking the layout, and why the build fails on overflow.
• The distinction between the committed build-time site card and the request-time blog OG SVGs.

Verification

• Confirmed the adapter-count derivation yields 23 against the current export map.
• Ran bun run og:generate — regenerates the PNG successfully (23 adapters, 6 sponsors); the regenerated asset was reverted so this stays a docs-only change.
• Verified every referenced file/symbol against source; the blog-fallback wording was corrected to match src/routes/blog/$slug.tsx (fallback when no post is resolved, not "posts without an image").

Want tembo to make any changes? Add a comment with @tembo and i'll get back to work!

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
email-sdk-fumadocs	Ready	Preview, Comment	Jul 7, 2026 11:26pm

[tembo]

Requesting review from @leoisadev1 who has experience with the following files modified in this PR:

• apps/fumadocs/README.md

[greptile-apps]

Greptile Summary

This PR documents the build-time site OG image system for the Fumadocs app. The main changes are:

• Adds where public/og/email-sdk.png is used for site and blog metadata.
• Explains how adapter count and sponsor data are derived from source files.
• Documents bun run og:generate, build integration, cache busting, deterministic rendering, and layout overflow guardrails.
• Adds common steps for updating sponsors and provider logos.

Confidence Score: 5/5

Safe to merge with minimal risk.

The change is limited to README documentation, and the referenced code paths match the current implementation.

No files require special attention.

T-Rex Logs

What T-Rex did

• Baseline og-generation status and PNG hash 8f7d568ebe13bd6ac3c257f0d0781814ef81ab475a26da62a683f3f83c70b26f were recorded from og-generation-01-before.log.
• The og:generate command completed successfully (exit code 0) with output indicating it wrote 135.2 KiB, 23 adapters, and 6 sponsors.
• Post-run verification showed the same PNG hash after generation and the documented count line was repeated in og-generation-03-status-and-counts.log.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
apps/fumadocs/README.md	Adds documentation for the build-time site OG image generation flow; references match the reviewed generator, metadata wiring, sponsor source, and build scripts.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Dev as Developer
participant Build as Build script
participant Gen as og:generate
participant Sources as package exports + sponsors
participant PNG as public/og/email-sdk.png
participant Meta as site/blog metadata

Dev->>Build: bun run build
Build->>Gen: bun scripts/og/generate-og-image.ts
Gen->>Sources: derive adapter count and sponsor row
Gen->>PNG: render committed site OG PNG
Meta->>PNG: reference as default OG/Twitter image
Meta->>PNG: use fallback when blog post is unresolved

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Dev as Developer
participant Build as Build script
participant Gen as og:generate
participant Sources as package exports + sponsors
participant PNG as public/og/email-sdk.png
participant Meta as site/blog metadata

Dev->>Build: bun run build
Build->>Gen: bun scripts/og/generate-og-image.ts
Gen->>Sources: derive adapter count and sponsor row
Gen->>PNG: render committed site OG PNG
Meta->>PNG: reference as default OG/Twitter image
Meta->>PNG: use fallback when blog post is unresolved

Loading

_{Reviews (1): Last reviewed commit: "docs(fumadocs): document build-time site..." | Re-trigger Greptile}

[tembo]

Greptile Summary

This PR documents the build-time site OG image system for the Fumadocs app. The main changes are:

• Adds where public/og/email-sdk.png is used for site and blog metadata.
• Explains how adapter count and sponsor data are derived from source files.
• Documents bun run og:generate, build integration, cache busting, deterministic rendering, and layout overflow guardrails.
• Adds common steps for updating sponsors and provider logos.

Confidence Score: 5/5

Safe to merge with minimal risk.

The change is limited to README documentation, and the referenced code paths match the current implementation.

No files require special attention.

T-Rex Logs

What T-Rex did

• Baseline og-generation status and PNG hash 8f7d568ebe13bd6ac3c257f0d0781814ef81ab475a26da62a683f3f83c70b26f were recorded from og-generation-01-before.log.
• The og:generate command completed successfully (exit code 0) with output indicating it wrote 135.2 KiB, 23 adapters, and 6 sponsors.
• Post-run verification showed the same PNG hash after generation and the documented count line was repeated in og-generation-03-status-and-counts.log.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
apps/fumadocs/README.md	Adds documentation for the build-time site OG image generation flow; references match the reviewed generator, metadata wiring, sponsor source, and build scripts.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant Dev as Developer
participant Build as Build script
participant Gen as og:generate
participant Sources as package exports + sponsors
participant PNG as public/og/email-sdk.png
participant Meta as site/blog metadata

Dev->>Build: bun run build
Build->>Gen: bun scripts/og/generate-og-image.ts
Gen->>Sources: derive adapter count and sponsor row
Gen->>PNG: render committed site OG PNG
Meta->>PNG: reference as default OG/Twitter image
Meta->>PNG: use fallback when blog post is unresolved

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant Dev as Developer
participant Build as Build script
participant Gen as og:generate
participant Sources as package exports + sponsors
participant PNG as public/og/email-sdk.png
participant Meta as site/blog metadata

Dev->>Build: bun run build
Build->>Gen: bun scripts/og/generate-og-image.ts
Gen->>Sources: derive adapter count and sponsor row
Gen->>PNG: render committed site OG PNG
Meta->>PNG: reference as default OG/Twitter image
Meta->>PNG: use fallback when blog post is unresolved

Loading

_{Reviews (1): Last reviewed commit: "docs(fumadocs): document build-time site..." | Re-trigger Greptile}

greptile's review on pr #157 came back a clean 5/5 — "safe to merge with minimal risk," no files flagged, and no change requests. i also checked for inline review threads and there are none.

so there's nothing actionable to implement here. the feedback actually validated the docs: greptile's t-rex ran bun run og:generate, confirmed it writes 135.2 kib with 23 adapters and 6 sponsors, and verified the referenced codepaths (generator, metadata wiring, sponsor source, build scripts) match the current implementation.

the pr is a docs-only change to apps/fumadocs/README.md and is ready to merge as-is. i left it untouched to keep the diff clean.