build-link-preview

Build link-preview cards

Assemble a rich preview for a URL: title, description, favicon, thumbnail image, and a WCAG-safe color scheme derived from the page's imagery.

Steps

1. Metadata — call microlink_meta for the card text and imagery:
   • microlink.data.title, .description, .author, .date, .publisher
   • microlink.data.image.url (hero image), microlink.data.logo.url (favicon)
2. Colors — call microlink_palette on the same URL to theme the card:
   • microlink.data.image.palette — dominant colors (most → least dominant)
   • microlink.data.image.background_color — best card background
   • microlink.data.image.color — readable text/overlay color (WCAG-contrast)
   • microlink.data.image.alternative_color — accent
3. Thumbnail (optional) — if the page has no good image, call microlink_screenshot with { "screenshot": { "type": "jpeg" } } and use microlink.data.screenshot.url as the fallback preview image.

To do it in a single request, use microlink_extract with palette: true (and screenshot: true if you also want a fallback thumbnail) — metadata, palette, and screenshot come back together under microlink.data.

{ "url": "https://example.com", "palette": true, "screenshot": true }

Render

Fill references/card-template.html with the values above. The template uses the palette so text stays readable on the chosen background. Minimal mapping:

• Background ← background_color
• Title / description text ← color
• Accent border/badge ← alternative_color (or palette[0])
• Thumbnail ← image.url (fallback: screenshot.url)
• Favicon + publisher ← logo.url + publisher

Tips & gotchas

• Always check status === "success" and that image.url exists before rendering; fall back to a screenshot thumbnail when it doesn't.
• Missing colors: palette data is nested under each image field (e.g. data.image.palette), not at the top level.
• Consistency: cache with a ttl (e.g. "1d") so repeated previews of the same link stay identical; use force: true only when you need to refresh.
• Accessibility: background_color + color are already chosen for contrast — use them together rather than mixing in arbitrary palette entries for body text.
• Free endpoint caps at 50 requests/day; set MICROLINK_API_KEY for more.