|$ curl https://forge-ai.dev/api/markdown?path=docs/html/opengraph
$cat docs/open-graph-&-seo.md
updated This week·35 min read·published
Open Graph & SEO
◆HTML◆SEO◆Social Media◆Intermediate
Introduction
When you share a link on social media, the platform fetches your page and extracts metadata to generate a rich preview — a title, description, image, and sometimes additional information like video or product price. This preview is powered by the Open Graph Protocol (OGP) and Twitter Cards, two standards that let you control how your content appears when shared.
The Open Graph Protocol, introduced by Facebook in 2010, defines a set of <meta> tags that describe a page's title, type, URL, image, and other properties. It has since been adopted by LinkedIn, Discord, Slack, Pinterest, and most other platforms. Twitter introduced its own Twitter Cards specification, which overlaps with Open Graph but adds platform-specific features.
Beyond social sharing, this section also covers traditional SEO meta tags — meta description, canonical, robots, and hreflang — which control how your page appears in search engine results. Together, these metadata elements form the foundation of search and social optimization for any web page.
Open Graph Protocol
The Open Graph Protocol enables any web page to become a rich object in a social graph. By adding og:meta properties to your <head>, you define how your page is represented on Facebook, LinkedIn, Discord, Slack, and other platforms that support the protocol.
| Property | Value | Required | Description |
|---|---|---|---|
| og:title | string | Yes | Title of the page (should match the page title, 40-60 chars) |
| og:description | string | Recommended | Brief description (2-4 sentences, max ~300 chars) |
| og:image | URL | Yes | URL of the image shown in the preview |
| og:image:width | number | Recommended | Image width in pixels (helps render faster) |
| og:image:height | number | Recommended | Image height in pixels |
| og:image:alt | string | Recommended | Accessible description of the image |
| og:url | URL | Yes | Canonical URL of the page (prevents duplicate shares) |
| og:type | string | Yes | The type of object (website, article, product, video, etc.) |
| og:locale | locale | Optional | Language locale (e.g., en_US, fr_FR, ja_JP) |
| og:site_name | string | Optional | Name of the overall site (appears above the title) |
| og:video | URL | Optional | URL of a video associated with the page |
| og:audio | URL | Optional | URL of an audio file associated with the page |
| fb:app_id | string | Optional | Facebook app ID (for Facebook Insights integration) |
open-graph-head.html
HTML
| 1 | <!-- Complete Open Graph header block --> |
| 2 | <head> |
| 3 | <title>Getting Started with Open Graph — Dev Guide</title> |
| 4 | |
| 5 | <!-- Open Graph required tags --> |
| 6 | <meta property="og:title" content="Getting Started with Open Graph — Dev Guide" /> |
| 7 | <meta property="og:description" content="Learn how to control your social media previews with Open Graph protocol and Twitter Cards. Complete guide with examples and best practices." /> |
| 8 | <meta property="og:image" content="https://example.com/images/og-guide-banner.png" /> |
| 9 | <meta property="og:image:width" content="1200" /> |
| 10 | <meta property="og:image:height" content="630" /> |
| 11 | <meta property="og:image:alt" content="Open Graph protocol diagram showing how meta tags become social previews" /> |
| 12 | <meta property="og:url" content="https://example.com/guides/opengraph" /> |
| 13 | <meta property="og:type" content="article" /> |
| 14 | <meta property="og:locale" content="en_US" /> |
| 15 | <meta property="og:site_name" content="Dev Guide" /> |
| 16 | |
| 17 | <!-- Type-specific: article --> |
| 18 | <meta property="article:published_time" content="2026-01-15T09:00:00Z" /> |
| 19 | <meta property="article:modified_time" content="2026-02-01T14:30:00Z" /> |
| 20 | <meta property="article:author" content="https://example.com/authors/jane" /> |
| 21 | <meta property="article:section" content="HTML" /> |
| 22 | <meta property="article:tag" content="opengraph" /> |
| 23 | <meta property="article:tag" content="seo" /> |
| 24 | <meta property="article:tag" content="social-media" /> |
| 25 | |
| 26 | <!-- Facebook-specific --> |
| 27 | <meta property="fb:app_id" content="1234567890" /> |
| 28 | |
| 29 | <!-- Duplicate image for WhatsApp (uses og:image) --> |
| 30 | <!-- WhatsApp also supports og:image directly --> |
| 31 | </head> |
✓
best practice
Always include og:title, og:description, og:image, og:url, and og:type on every page. These five tags are required or strongly recommended by every major platform. The title should be 40-60 characters, the description 2-4 sentences, and the image should be 1200x630px (1.91:1 aspect ratio).
Open Graph Types
The og:type property tells platforms what kind of object your page represents. Different types support additional properties that enhance the preview.
| Type | Use Case | Additional Properties |
|---|---|---|
| website | General web pages, landing pages | None |
| article | Blog posts, news articles, press releases | article:published_time, article:modified_time, article:author, article:section, article:tag |
| product | E-commerce product pages | product:price:amount, product:price:currency, product:availability |
| video.movie | Movie pages | video:duration, video:release_date, video:director, video:actor |
| video.episode | TV show episodes | video:series, video:episode, video:season |
| music.song | Music track pages | music:duration, music:album, music:musician |
| profile | User profile pages | profile:first_name, profile:last_name, profile:username |
| book | Book pages | book:author, book:isbn, book:release_date |
og-types.html
HTML
| 1 | <!-- Product type (e-commerce) --> |
| 2 | <head> |
| 3 | <meta property="og:type" content="product" /> |
| 4 | <meta property="og:title" content="Noise-Cancelling Headphones" /> |
| 5 | <meta property="og:description" content="Premium wireless headphones with 30h battery life." /> |
| 6 | <meta property="og:image" content="https://example.com/img/headphones.jpg" /> |
| 7 | <meta property="product:price:amount" content="149.99" /> |
| 8 | <meta property="product:price:currency" content="USD" /> |
| 9 | <meta property="product:availability" content="in stock" /> |
| 10 | <meta property="product:brand" content="SoundPro" /> |
| 11 | <meta property="product:retailer_item_id" content="NC-WH-2026" /> |
| 12 | </head> |
| 13 | |
| 14 | <!-- Article type (blog/news) --> |
| 15 | <head> |
| 16 | <meta property="og:type" content="article" /> |
| 17 | <meta property="og:title" content="How Open Graph Works" /> |
| 18 | <meta property="article:published_time" content="2026-01-15T09:00:00Z" /> |
| 19 | <meta property="article:modified_time" content="2026-02-01T14:30:00Z" /> |
| 20 | <meta property="article:author" content="https://example.com/authors/jane" /> |
| 21 | <meta property="article:section" content="Technology" /> |
| 22 | <meta property="article:tag" content="open-graph" /> |
| 23 | <meta property="article:tag" content="web-development" /> |
| 24 | </head> |
| 25 | |
| 26 | <!-- Profile type (user pages) --> |
| 27 | <head> |
| 28 | <meta property="og:type" content="profile" /> |
| 29 | <meta property="og:title" content="Jane Doe — Developer" /> |
| 30 | <meta property="profile:first_name" content="Jane" /> |
| 31 | <meta property="profile:last_name" content="Doe" /> |
| 32 | <meta property="profile:username" content="janedoe" /> |
| 33 | </head> |
Twitter Cards
Twitter Cards extend the Open Graph protocol with Twitter-specific metadata. The twitter:card tag is required to enable rich previews on X (formerly Twitter). There are four card types:
| Card Type | Value | Description |
|---|---|---|
| Summary Card | summary | Small thumbnail (120x120px) + title + description. Best for articles and blog posts with limited image real estate. |
| Summary Card with Large Image | summary_large_image | Large hero image (1200x628px) + title + description. Best for content marketing, products, and visual content. 2-3x higher engagement. |
| App Card | app | Deep link to a mobile app with download buttons. Includes iPhone/iPad/Google Play IDs and custom app description. |
| Player Card | player | Embedded video or audio player (similar to Vine/YouTube embeds). Requires player URL, width, height, and stream URL. |
twitter-cards.html
HTML
| 1 | <!-- Summary Card with Large Image (recommended for most pages) --> |
| 2 | <head> |
| 3 | <meta name="twitter:card" content="summary_large_image" /> |
| 4 | <meta name="twitter:site" content="@example" /> |
| 5 | <meta name="twitter:creator" content="@janedoe" /> |
| 6 | <meta name="twitter:title" content="Getting Started with Open Graph" /> |
| 7 | <meta name="twitter:description" content="A complete guide to Open Graph and Twitter Cards for controlling social media previews." /> |
| 8 | <meta name="twitter:image" content="https://example.com/images/og-banner.png" /> |
| 9 | <meta name="twitter:image:alt" content="Open Graph protocol diagram" /> |
| 10 | </head> |
| 11 | |
| 12 | <!-- Summary Card (small thumbnail) --> |
| 13 | <head> |
| 14 | <meta name="twitter:card" content="summary" /> |
| 15 | <meta name="twitter:site" content="@example" /> |
| 16 | <meta name="twitter:title" content="Quick Tip: Open Graph" /> |
| 17 | <meta name="twitter:description" content="Short tip about Open Graph tags." /> |
| 18 | <meta name="twitter:image" content="https://example.com/images/thumbnail.png" /> |
| 19 | </head> |
| 20 | |
| 21 | <!-- App Card (mobile app deep linking) --> |
| 22 | <head> |
| 23 | <meta name="twitter:card" content="app" /> |
| 24 | <meta name="twitter:app:name:iphone" content="MyApp" /> |
| 25 | <meta name="twitter:app:id:iphone" content="123456789" /> |
| 26 | <meta name="twitter:app:name:ipad" content="MyApp" /> |
| 27 | <meta name="twitter:app:id:ipad" content="123456789" /> |
| 28 | <meta name="twitter:app:name:googleplay" content="MyApp" /> |
| 29 | <meta name="twitter:app:id:googleplay" content="com.example.myapp" /> |
| 30 | <meta name="twitter:app:url:iphone" content="myapp://page/id" /> |
| 31 | <meta name="twitter:app:url:googleplay" content="myapp://page/id" /> |
| 32 | </head> |
| 33 | |
| 34 | <!-- Player Card (video) --> |
| 35 | <head> |
| 36 | <meta name="twitter:card" content="player" /> |
| 37 | <meta name="twitter:title" content="Video Title" /> |
| 38 | <meta name="twitter:description" content="Video description." /> |
| 39 | <meta name="twitter:image" content="https://example.com/video-thumb.jpg" /> |
| 40 | <meta name="twitter:player" content="https://example.com/player" /> |
| 41 | <meta name="twitter:player:width" content="1280" /> |
| 42 | <meta name="twitter:player:height" content="720" /> |
| 43 | <meta name="twitter:player:stream" content="https://example.com/stream.mp4" /> |
| 44 | </head> |
Combine Open Graph and Twitter Card tags for maximum compatibility. Twitter will use og:title, og:description, and og:image as fallbacks if the Twitter-specific tags are missing, but explicit Twitter tags let you customize the experience per platform:
combined-og-twitter.html
HTML
| 1 | <!-- Combined OG + Twitter Cards (recommended approach) --> |
| 2 | <head> |
| 3 | <title>Complete Guide to OG & Twitter Cards</title> |
| 4 | |
| 5 | <!-- === Open Graph === --> |
| 6 | <meta property="og:title" content="Complete Guide to OG & Twitter Cards" /> |
| 7 | <meta property="og:description" content="Master social media previews with this comprehensive guide to Open Graph and Twitter Cards." /> |
| 8 | <meta property="og:image" content="https://example.com/images/og-banner.png" /> |
| 9 | <meta property="og:image:width" content="1200" /> |
| 10 | <meta property="og:image:height" content="630" /> |
| 11 | <meta property="og:image:alt" content="Social media preview card" /> |
| 12 | <meta property="og:url" content="https://example.com/guides/og-complete" /> |
| 13 | <meta property="og:type" content="article" /> |
| 14 | <meta property="og:site_name" content="Dev Guides" /> |
| 15 | <meta property="og:locale" content="en_US" /> |
| 16 | |
| 17 | <!-- === Twitter Cards === --> |
| 18 | <meta name="twitter:card" content="summary_large_image" /> |
| 19 | <meta name="twitter:site" content="@devguides" /> |
| 20 | <meta name="twitter:creator" content="@authorhandle" /> |
| 21 | <!-- twitter:title/description/image fall back to og: if missing, |
| 22 | but explicit tags allow platform-specific customization --> |
| 23 | <meta name="twitter:title" content="Complete Guide to OG & Twitter Cards" /> |
| 24 | <meta name="twitter:description" content="Master social media previews — a comprehensive guide to Open Graph and Twitter Cards for developers." /> |
| 25 | <meta name="twitter:image" content="https://example.com/images/twitter-banner.png" /> |
| 26 | <meta name="twitter:image:alt" content="Social media preview card" /> |
| 27 | </head> |
🔥
pro tip
You can use different images for Twitter and other platforms by providing separate twitter:image and og:image URLs. This is useful when you want to optimize aspect ratios — Twitter's large card works best with 2:1 (1200x628), while Facebook and LinkedIn prefer 1.91:1 (1200x630). The difference is subtle but can affect how your preview is cropped.
Structured Data for SEO
Beyond social sharing, critical SEO metadata in the <head> controls how search engines index and display your page. These tags affect ranking, indexing behavior, and the search result appearance.
| Tag | Purpose | Example |
|---|---|---|
| meta description | Page description shown in search results (under the title) | <meta name="description" content="..." /> |
| link canonical | Specifies the preferred URL when duplicate content exists | <link rel="canonical" href="..." /> |
| meta robots | Controls indexing and crawling behavior | <meta name="robots" content="index, follow" /> |
| link hreflang | Specifies language/region alternatives for international pages | <link rel="alternate" hreflang="fr" href="..." /> |
| meta viewport | Controls page width and scaling on mobile devices | <meta name="viewport" content="width=device-width" /> |
| meta charset | Declares character encoding (must be UTF-8) | <meta charset="UTF-8" /> |
seo-head-block.html
HTML
| 1 | <!-- Complete SEO header block --> |
| 2 | |
| 3 | <head> |
| 4 | <title>SEO & Social Media Optimization Guide | Site Name</title> |
| 5 | |
| 6 | <!-- Charset + Viewport (essential for all pages) --> |
| 7 | <meta charset="UTF-8" /> |
| 8 | <meta name="viewport" content="width=device-width, initial-scale=1.0" /> |
| 9 | |
| 10 | <!-- Meta Description — shown in search results --> |
| 11 | <meta name="description" |
| 12 | content="A complete guide to Open Graph, Twitter Cards, and SEO meta tags. Learn how to control your social previews and search snippets." /> |
| 13 | |
| 14 | <!-- Canonical URL — prevents duplicate content issues --> |
| 15 | <link rel="canonical" href="https://example.com/guides/seo-optimization" /> |
| 16 | |
| 17 | <!-- Robots — index this page, follow links (default behavior) --> |
| 18 | <meta name="robots" content="index, follow, max-snippet:-1, max-image-preview:large" /> |
| 19 | |
| 20 | <!-- Hreflang — internationalization --> |
| 21 | <link rel="alternate" hreflang="en" href="https://example.com/guides/seo-optimization" /> |
| 22 | <link rel="alternate" hreflang="fr" href="https://example.com/fr/guides/optimisation-seo" /> |
| 23 | <link rel="alternate" hreflang="de" href="https://example.com/de/guides/seo-optimierung" /> |
| 24 | <link rel="alternate" hreflang="x-default" href="https://example.com/guides/seo-optimization" /> |
| 25 | |
| 26 | <!-- Verification (search console) --> |
| 27 | <meta name="google-site-verification" content="..." /> |
| 28 | <meta name="msvalidate.01" content="..." /> |
| 29 | |
| 30 | <!-- Pagination (for paginated content) --> |
| 31 | <link rel="prev" href="https://example.com/guides/page/1" /> |
| 32 | <link rel="next" href="https://example.com/guides/page/3" /> |
| 33 | |
| 34 | <!-- Sitemap reference --> |
| 35 | <link rel="sitemap" type="application/xml" title="Sitemap" href="/sitemap.xml" /> |
| 36 | </head> |
⚠
warning
The max-snippet:-1 and max-image-preview:large in the robots meta tag are recommended for most content pages. max-snippet:-1 means no snippet length limit (Google can choose the best snippet). max-image-preview:large allows large images in search results. Never use noindex on pages you want in search results.
Social Preview Best Practices
The most important element of a social preview is the image. A well-designed preview image can dramatically improve engagement rates. Here are the key specifications and design guidelines:
| Platform | Image Size | Aspect Ratio | Max Title | Max Description |
|---|---|---|---|---|
| 1200 x 630px | 1.91:1 | ~60 chars | ~200 chars | |
| Twitter (large) | 1200 x 628px | 2:01:1 | ~70 chars | ~200 chars |
| 1200 x 627px | 1.91:1 | ~60 chars | ~150 chars | |
| Discord | 1200 x 630px | 1.91:1 | ~50 chars | ~300 chars |
| Slack | 256 x 256px (cropped) | 1:1 | ~80 chars | ~300 chars |
| 1200 x 630px | 1.91:1 | ~50 chars | ~200 chars |
Design guidelines for social preview images:
◆Use 1200 x 630px as your base image size (safe zone for all platforms). Keep essential content and text within the center 1000 x 520px safe zone to avoid cropping.
◆Keep text minimal. Most platforms apply text overlays (page title) over the image. Avoid putting critical information in the top 200px or bottom 200px.
◆Use high-contrast colors and readable fonts. The image thumbnail is small in feeds — text should be large and bold if included.
◆Include your brand logo in a consistent position (bottom-left or bottom-right corner) for brand recognition.
◆Use unique, page-specific images rather than a generic site-wide image. Unique images improve engagement and help users distinguish between shares from the same domain.
◆Avoid images with fine detail or small text. They become illegible when rendered at preview size (typically 300-500px wide in feeds).
◆Test your image on multiple platforms using the platform-specific debugger tools before publishing.
Title and description character limits:
◆og:title: 40-60 characters for optimal display. Titles longer than 60 chars are truncated on most platforms.
◆og:description: 2-4 sentences (150-200 characters). Descriptions over 200 chars are truncated on Facebook and LinkedIn.
◆Page title (<title>): 50-60 characters for SEO. This is separate from og:title and can be different if needed.
◆Meta description: 150-160 characters for optimal search snippet display. Google may use more or less depending on content.
⚠
warning
The most common social preview mistake is using an image that is too small or has the wrong aspect ratio. If your og:image is smaller than 600x315px, Facebook will show it as a small thumbnail instead of a large hero image. Always provide og:image:width and og:image:height to help platforms render the preview faster and more reliably.
Testing Tools
Always test how your page appears when shared before publishing. These debugging tools let you inspect how each platform renders your content and identify issues.
Facebook Sharing Debugger
The Facebook Sharing Debugger (developers.facebook.com/tools/debug) shows exactly how your page appears when shared on Facebook. It displays all extracted OG tags, the rendered preview, and any warnings or errors. It also lets you force-refresh Facebook's cache for your URL, which is essential when you update OG tags.
Twitter Card Validator
The Twitter Card Validator (cards-dev.twitter.com/validator) lets you preview how your page appears in Twitter timelines. Enter your URL and it shows the rendered card, extracted tags, and any errors. Note: you must have twitter:card set for the validator to work.
LinkedIn Post Inspector
The LinkedIn Post Inspector (linkedin.com/post-inspector) validates your page's Open Graph tags and shows the preview as it appears in LinkedIn feeds. It also reports any issues with missing or invalid tags.
Pinterest Rich Pins Validator
For Pinterest, use the Rich Pins Validator (developers.pinterest.com/tools/url-debugger) to validate that your page supports Rich Pins (product, recipe, or article pins). Pinterest requires Open Graph tags plus additional Pinterest-specific metadata.
Google Rich Results Test
While primarily for Schema.org structured data, the Google Rich Results Test also validates your page's indexability and can help identify SEO meta tag issues. Use it alongside platform-specific debuggers for a complete picture.
Quick-reference debugger URLs:
| Platform | Debugger URL |
|---|---|
| developers.facebook.com/tools/debug | |
| Twitter / X | cards-dev.twitter.com/validator |
| linkedin.com/post-inspector | |
| developers.pinterest.com/tools/url-debugger | |
| search.google.com/test/rich-results |
✓
best practice
Always validate after deploying OG tag changes. Facebook and other platforms cache preview data — sometimes for 24-48 hours. The debugger tools let you force a cache refresh immediately. Make a habit of running each URL through the relevant debugger when you publish new content or update existing pages.
Live preview of how Open Graph and Twitter Card tags render as a social card:
Best Practices
◆Always include og:title, og:description, og:image, og:url, and og:type on every page. These are the minimum tags every platform needs.
◆Set twitter:card to summary_large_image on all pages. It improves engagement by making your content visually prominent in timelines.
◆Use separate og:image and twitter:image URLs when you need platform-specific image cropping or aspect ratios.
◆Keep og:title under 60 characters and og:description under 200 characters for optimal cross-platform display.
◆Use absolute URLs (including https://) for all og:image, og:url, and twitter:image values. Relative URLs may not work correctly.
◆Always specify og:image:width and og:image:height. This helps platforms render previews faster and avoids layout shifts.
◆Provide an og:image:alt attribute for accessibility. Screen readers and some platforms use this when the image cannot be displayed.
◆Use the Facebook Sharing Debugger, Twitter Card Validator, and LinkedIn Post Inspector after every deployment.
◆Set up a default og:image for your site that is used when a page does not define its own. This ensures every shared page has some preview image.
◆Cache-bust OG images when you update them. Add a query parameter (?v=2) to the image URL and run the debugger to force a refresh.
ℹ
info
Build a reusable template or component for your OG tags. A consistent implementation across your site prevents missing tags on individual pages. For Next.js, use the metadata export or <Head> component. For static sites, use your templating engine's partial/include system. Automate validation with a build step that checks for required OG tags using a tool like html-validator or a custom script.
$Blueprint — Engineering Documentation·Section ID: HTML-30·Revision: 1.0
Each social platform has slightly different behavior when rendering shared links. Understanding these differences helps you optimize your previews for each platform.
Facebook
Uses the Open Graph protocol natively. Facebook's scraper re-fetches your page every 24 hours or when the share count is reset via the Sharing Debugger. Image size should be at least 1200x630px. Title is truncated at ~60 characters. Description is capped at ~200 characters in previews. Facebook prefers og:image:width and og:image:height for faster rendering. The fb:app_id property enables Facebook Insights for your domain.
Twitter / X
Twitter uses its own Twitter Cards syntax (twitter:card, twitter:title, etc.) but falls back to Open Graph tags when Twitter-specific tags are missing. The twitter:card property is required to enable rich previews. The large image card (summary_large_image) performs significantly better than summary card. Image size: at least 1200x628px for large cards.
LinkedIn
LinkedIn uses Open Graph tags directly. The post inspector (previously called LinkedIn Post Inspector) shows exactly how your page will appear when shared. LinkedIn supports the article:author and article:published_time properties. Image size should be at least 1200x627px. Description is truncated at ~150 characters.
Discord
Discord uses Open Graph and Twitter Card tags to generate link embeds. It prefers og:image for the preview thumbnail. Discord embeds show the title, description, image, and site name. If no og:image is provided, Discord shows a generic link card without a preview image.
Slack
Slack uses Open Graph to generate unfurl previews. Image is shown at 256x256px square crop from the center of your og:image. Slack supports og:title, og:description, og:image, and og:url. The site name appears as the source label.
WhatsApp
WhatsApp uses Open Graph tags for link previews. Image size recommendations are 1200x630px. WhatsApp caches previews aggressively and may not update even after clearing the Facebook cache. The preview includes title, description, and image in a card layout.
info