Open Graph and Social Preview Meta Tags: Build and Debug Link Previews
open-graphtwitter-cardsseofrontendmeta-tagscontent-publishing

Open Graph and Social Preview Meta Tags: Build and Debug Link Previews

CCode Craft Hub Editorial Team
2026-11-08
6 min read

Use this Open Graph and social card checklist to build accurate link previews and debug wrong images, titles, descriptions, and cached metadata.

When a shared link displays the wrong title, image, or description, the problem is usually found in page metadata, image delivery, or a crawler cache rather than in the visible page design. This checklist explains how Open Graph and social card tags work, provides a reusable HTML template, and gives you a practical workflow for building and debugging link previews before publishing.

Overview

Social platforms, messaging clients, and other services can inspect the HTML of a URL and use metadata to create a link preview. The visible result may include a title, summary, image, site name, and canonical URL. Different clients may interpret the same page differently, so a reliable setup uses clear metadata, accessible assets, and a repeatable testing process.

Open Graph meta tags are the broad foundation for social previews. They use the og: namespace and describe the shared object, such as an article, product page, or home page. Twitter Card tags, now encountered in clients associated with the X platform as well as other tools, provide additional card-related instructions. In many implementations, the Twitter-specific tags complement rather than replace Open Graph values.

PurposeOpen GraphTwitter Card
Page titleog:titletwitter:title
Summaryog:descriptiontwitter:description
Preview imageog:imagetwitter:image
Page URLog:urlUsually inferred from the page URL
Content typeog:typeNot generally required
Card presentationNot specified by Open Graphtwitter:card

A useful baseline template looks like this:

<meta property="og:type" content="article">
<meta property="og:title" content="Your page title">
<meta property="og:description" content="A concise description of the page.">
<meta property="og:url" content="https://example.com/page">
<meta property="og:image" content="https://example.com/images/page-share.jpg">
<meta property="og:image:alt" content="Descriptive alternative text for the preview image">

<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Your page title">
<meta name="twitter:description" content="A concise description of the page.">
<meta name="twitter:image" content="https://example.com/images/page-share.jpg">
<meta name="twitter:image:alt" content="Descriptive alternative text for the preview image">

Place these elements in the document’s <head>. Generate them from the same page data used for the title and canonical URL, but do not assume that the browser’s visible content automatically supplies every social value.

Checklist by scenario

For a new article or landing page

  • Write a specific og:title that identifies the page without relying on surrounding navigation.
  • Use a useful og:description that explains the page’s value rather than repeating a generic site tagline.
  • Set og:url to the preferred, public URL, including the correct protocol and path.
  • Choose an image designed for sharing: readable at a small size, visually clear, and not dependent on text at the edges.
  • Set og:type appropriately. An article page and a general site homepage do not necessarily represent the same type of object.
  • Add Twitter Card values when the target clients or your publishing workflow support them.

When replacing a social preview image

  • Change the image URL or filename when practical. A new URL makes it easier to distinguish the new asset from a cached version.
  • Confirm that the image is publicly reachable without a login, temporary session, or browser-only interaction.
  • Check the response headers, redirects, and final content type. The URL should deliver an actual image rather than an HTML error page.
  • Retest the page in the sharing or preview tools available for the platforms you use.

When debugging a wrong title, description, or image

  1. View the deployed page source, not only the framework or CMS template.
  2. Search for every instance of og:title, og:description, og:image, and the corresponding Twitter tags. Duplicate declarations can produce confusing results.
  3. Copy the exact image URL into a private browser window and confirm that it loads without authentication.
  4. Compare the metadata URL with the URL being shared. Trailing slashes, query parameters, redirects, and alternate protocols can cause services to treat pages as different resources.
  5. Use a platform-specific preview or inspection tool where available, then allow for crawler caching before concluding that the markup failed.

What to double-check

Image dimensions and composition: There is no single image size that guarantees identical results across every sharing client. A practical social media preview image should use a landscape composition, preserve important content inside a safe central area, and remain legible when reduced. Check the current requirements of the platforms that matter to your audience before creating a reusable design system. Keep the source image large enough for the intended card, but avoid unnecessarily heavy files.

Image format and delivery: Use a widely supported image format and verify that your server returns the correct content type. Make sure the asset is served over HTTPS, uses a stable URL, and is not blocked by access rules, a firewall, or a robots configuration that prevents the relevant crawler from retrieving it. The page itself may be public while its image directory remains restricted.

Canonical and shared URLs: Social metadata does not replace canonicalization. If several URLs show the same page, decide which URL should be shared and keep og:url, the canonical link element, internal links, and campaign practices consistent. A preview may be correct for one URL and appear stale for another because the crawler stores them separately.

Rendered versus source HTML: Some crawlers may not execute JavaScript in the same way as a modern browser. For dependable previews, emit the essential tags in server-rendered or statically generated HTML whenever possible. Inspect the raw response from the deployed server to verify that the metadata exists before client-side scripts run.

Text length and accuracy: Titles and descriptions can be truncated by the receiving client. Put the identifying information first, avoid unnecessary repetition, and ensure that the description matches the page currently available at the URL. Alt text for the preview image should describe its meaning; it is not a substitute for a visible caption or page accessibility text.

Common mistakes

  • Using a relative image URL: Social crawlers need a complete, absolute URL such as https://example.com/images/share.jpg.
  • Testing only while logged in: Your browser session may hide an authentication or permission problem that affects external crawlers.
  • Editing the wrong template: A page may inherit metadata from a layout, CMS field, route, or default fallback. Inspect the final HTML for the exact URL.
  • Leaving stale duplicate tags: A component and a global layout may both output metadata. Keep one authoritative value for each property.
  • Putting critical text at the image edge: Cropping varies by card format and device. Keep logos, labels, and faces away from the edges.
  • Assuming a refresh is immediate: Link previews can be cached by more than one service. Updating the page does not guarantee that an existing preview changes at once.
  • Including sensitive information: Treat metadata and preview images as public. Do not expose private project names, customer data, tokens, or internal URLs.

When to revisit

Recheck social metadata before a seasonal campaign, product launch, major content update, or site redesign. It is also worth revisiting when you change your CMS, routing, image pipeline, CDN, deployment architecture, or domain configuration. Platform behavior and recommended image specifications can change, so review the current guidance for the clients that are important to your publishing workflow rather than treating a dimension checklist as permanent.

For routine maintenance, add a preview check to your release checklist. Test a representative homepage, article, product page, and error-prone route such as a page with query parameters or a redirect. If a preview breaks, follow this order: inspect deployed source, verify the exact URLs, fetch the image without a session, remove duplicate tags, republish if necessary, and then retest through the relevant inspection tools. Keep a small record of the expected title, description, image URL, and canonical URL for important templates.

Good metadata is part of frontend quality: it connects the page your team builds with the way people encounter it outside the site. Once the template and debugging sequence are documented, fixing a broken link card becomes a defined implementation task rather than guesswork. For related workflow references, see the CSS debugging tools guide and the frontend debugging workflow.

Related Topics

#open-graph#twitter-cards#seo#frontend#meta-tags#content-publishing
C

Code Craft Hub Editorial Team

Technical Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.