social-metadata-hardening | antigravity-awesome-skills

Stats

Actions

Tags

social-metadata-hardening | antigravity-awesome-skills

Social Metadata Hardening Skill

Fix social sharing so every important URL unfurls as a rich card across all platforms.

When to Use

Use when shared links show missing, stale, cropped, or incorrect previews on social and chat platforms.
Use when auditing Open Graph, Twitter/X card, image URL, alt text, or metadataBase coverage in a web app.
Use before launch when every public page needs predictable rich previews across LinkedIn, X, Facebook, WhatsApp, Slack, Discord, and Telegram.

Why Previews Break

Problem	Root Cause
No preview at all	Missing og:title, og:description, or og:image
Broken image	Relative URL (must be absolute)
Wrong image size	Image not 1200×630px (OG standard)
Plain text card	Twitter card type missing or set to `summary`
Stale preview	Platform caching old metadata
Metadata missing on crawl	Tags added by client-side JS (crawlers don't run JS)

The Gold Standard Metadata Block

Every shareable page needs ALL of these in static HTML:

// Next.js App Router — lib/socialMetadata.js
export function buildSocialMetadata({
  title,
  description,
  path,          // '/blog/my-post'
  image,         // '/images/og/my-post.jpg' or full URL
  imageAlt,
  imageWidth = 1200,
  imageHeight = 630,
}) {
  const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || 'https://www.yourdomain.com';
  
  // Always produce an absolute URL
  const imageUrl = image?.startsWith('http') ? image : `${baseUrl}${image}`;
  const pageUrl  = `${baseUrl}${path}`;
  
  // Detect MIME type from extension
  const ext = imageUrl.split('.').pop().toLowerCase();
  const mimeMap = { jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png', webp: 'image/webp' };
  const imageType = mimeMap[ext] || 'image/jpeg';

  return {
    title,
    description,
    alternates: { canonical: pageUrl },
    openGraph: {
      title,
      description,
      url: pageUrl,
      type: 'website',  // use 'article' for blog posts
      images: [{
        url: imageUrl,
        secureUrl: imageUrl,   // explicit HTTPS version
        width: imageWidth,
        height: imageHeight,
        alt: imageAlt || title,
        type: imageType,
      }],
    },
    twitter: {
      card: 'summary_large_image',  // NOT 'summary' — that shows a tiny image
      title,
      description,
      images: [imageUrl],
    },
  };
}

Applying the Helper

Static page

// app/about/page.js
import { buildSocialMetadata } from '@/lib/socialMetadata';

export const metadata = buildSocialMetadata({
  title: 'About Us | My Site',
  description: 'Learn about our team and mission.',
  path: '/about',
  image: '/images/og/about.jpg',
  imageAlt: 'The My Site team',
});

Dynamic page (blog post, tool page)

// app/blog/[slug]/page.js
import { buildSocialMetadata } from '@/lib/socialMetadata';

export async function generateMetadata({ params }) {
  const post = await getPost(params.slug);
  return buildSocialMetadata({
    title: `${post.title} | My Blog`,
    description: post.excerpt,
    path: `/blog/${params.slug}`,
    image: post.ogImage || '/images/og/default.jpg',
    imageAlt: post.title,
  });
}

Homepage (app/layout.js or app/page.js)

export const metadata = {
  metadataBase: new URL('https://www.yourdomain.com'), // REQUIRED for absolute URLs
  ...buildSocialMetadata({
    title: 'My Site — Tagline Here',
    description: 'Site-wide description.',
    path: '/',
    image: '/images/og/home.jpg',
  }),
};

⚠️ Set metadataBase when using relative metadata URLs. If your helper already outputs absolute canonical/OG URLs, previews can still work without it.

OG Image Checklist

Good OG images:

1200 × 630px (2:1 ratio — works on all platforms)
Under 8MB (Facebook limit)
Served over HTTPS
File name has no spaces (use hyphens)
Format: JPEG or PNG (WebP works on most but not all crawlers)
Accessible via GET with no authentication

# Verify your OG image is reachable and correct size
curl -sI https://www.yourdomain.com/images/og/home.jpg | grep -i "content-type\|content-length\|status"

Platform-Specific Notes

Facebook / Meta

Caches aggressively — use the Sharing Debugger to force recrawl
Minimum image: 200×200px (but use 1200×630 for quality)
Needs: og:title, og:description, og:image, og:url

X / Twitter

Use twitter:card = summary_large_image for full-width images
twitter:image must be an absolute URL
Use the Card Validator to test

LinkedIn

Caches hard — use Post Inspector to refresh
Respects og: tags; ignores twitter: tags
Image must be ≥1.91:1 aspect ratio

WhatsApp / Telegram

Read OG tags on first share; cache can last hours
Re-share after a few hours for the cache to clear naturally

Slack / Discord

Both use OG tags; both cache
Discord also supports og:type = article for richer embeds

Debugging Social Previews

1. Check raw HTML for tags

curl -s https://www.yourdomain.com/blog/my-post | grep -i "og:\|twitter:"

If tags don't appear → they're being added by JavaScript (not crawlable). Fix: move to export const metadata or generateMetadata.

2. Validate with platform tools

Platform	Tool
Facebook	https://developers.facebook.com/tools/debug/
LinkedIn	https://www.linkedin.com/post-inspector/
Twitter/X	https://cards-dev.twitter.com/validator
General	https://metatags.io

3. Force cache refresh

After deploying fixes, paste the URL into each platform's debugger and click "Fetch new scrape information" (or equivalent).

Social Metadata Checklist

Limitations

Cannot force immediate cache refresh on every social platform; some previews may remain stale after a correct fix.
Requires publicly reachable deployed URLs for reliable validation with platform debuggers.
Does not replace brand, accessibility, or legal review of image text, alt text, and preview copy.