Skip to main content

Open Graph

Paste a link into a chat and, a moment later, a neat card appears with a picture, a title, and a short line of text. That card was not made by magic, and it was not made by the chat app guessing. It was built from a few small tags in your page's head, called Open Graph tags.

If you do not add them, apps take a guess, and the guess is often a blurry image (or none at all) and the wrong words. If you add them, you decide how your page introduces itself to the world.


What You Will Learn​

  • What Open Graph is, and who reads it
  • The four essential tags, and the helpful extras
  • How to choose and size a share image
  • Why you need full addresses and server-side HTML
  • How caching works, and how to refresh a preview
  • How Open Graph relates to title, description, and canonical
  • How to test your tags

The Big Idea​

index.html
<head>
  <title>Easy No-Knead Rye Bread | The Bread Bin</title>

  <meta property="og:type" content="article">
  <meta property="og:title" content="Easy No-Knead Rye Bread">
  <meta property="og:description" content="Bake a crusty rye loaf at home with five simple ingredients, and no kneading.">
  <meta property="og:url" content="https://thebreadbin.example/recipes/rye-bread">
  <meta property="og:image" content="https://thebreadbin.example/img/rye-1200x630.jpg">
  <meta property="og:image:alt" content="A rye loaf cooling on a wooden board">
</head>

Change the title, the image shape, and the type. Watch the card, the tags, and the checks.

What Open Graph Is​

Open Graph is a small set of tags first created by Facebook, and now read by many other apps: social networks, chat apps, collaboration tools, and link-preview services. When someone shares your link, the app fetches your page, reads the tags, and draws a card.

  • It is not for search rankings. Open Graph does not directly help your search position. Its job is to make shared links look good, and a good-looking link gets more clicks.
  • It uses property, not name. Open Graph tags are written property="og:title". (Many parsers also accept name, but follow the standard.)
  • It lives in the head. Like all meta tags.

The Four Essential Tags​

TagWhat it saysExample
og:titleThe headline of the cardEasy No-Knead Rye Bread
og:typeWhat kind of thing this isarticle or website
og:imageThe picture for the cardA full https address
og:urlThe main address of the pageThe canonical address

Add these, and you have the foundation. Then add the helpful extras:

ExtraWhy
og:descriptionOne or two lines under the title
og:image:altA text description of the picture, for accessibility
og:image:width and og:image:heightHelps apps lay out the card on the first share
og:site_nameThe name of your site, shown above or below the title
og:localeThe language and region, such as en_US or fr_FR
article:published_timeThe date, for articles (ISO format)
article:author and article:sectionMore about an article

Choosing og:type​

  • website for your home page and general pages.
  • article for blog posts, recipes, and news. It unlocks the article: tags.
  • Others, such as book, profile, video.movie, and music.song, exist for those kinds of content.

If you are unsure, website is a safe default. Some apps ignore the type altogether.

Choosing a Share Image​

The image is the part of the card that people notice first, and the one that most often goes wrong.

  • Use a wide image, about 1200 by 630 pixels (roughly 1.91 to 1). This is a common size that many apps display as a large card. Check each platform's current guidance, as sizes change.
  • Use JPG, PNG, or WebP. Most apps do not accept SVG.
  • Keep the file size sensible. Large files may be skipped by some apps, and are slow on mobile data. A few hundred kilobytes is usually plenty.
  • Make it a full address, starting with https://. Relative paths such as /img/rye.jpg do not work, because the app is not on your site.
  • The image must be public. If it is behind a login, the app cannot fetch it.
  • Keep the important parts in the middle. Cards crop images in different ways.
  • Put text in the image carefully. It must be large and short, because the card is small. It should also be in the page's text somewhere, for accessibility.
  • Always add og:image:alt.
  • Do not use the same image for every page. A unique image per page makes shared links much more recognisable.

See how different shapes crop:

http://127.0.0.1:5500/index.html
Choose the shape of your share image

Your full image

Corner textMain subjectLogo

What a large card may show

Corner textMain subjectLogo

About 52 percent of the picture is visible in a wide card.

Parts of the edges are cut off. Keep important text and logos near the middle.

This simulates one common way of fitting a picture into a wide card, which is to fill the space and trim the edges. Some apps instead show a small square thumbnail, or add bars. Always keep text and key details in the middle, and test the real result.

Full Addresses and Clean URLs​

  • All addresses must be absolute, with https://. This goes for og:image and og:url.
  • og:url should be the canonical address, with no tracking parameters, so that every share of the same page is counted and displayed as one. See Canonical Links.
  • Do not point og:url at a redirect, or at a different page.

What Apps Do When Tags Are Missing​

Most apps have a fallback chain:

  • No og:title: use the page's <title>.
  • No og:description: use the meta description, or text from the page.
  • No og:image: look for another image on the page, or show a text-only card.

That is why a page with no Open Graph tags still gets a preview, and why the preview is so often poor. Fallbacks vary by app, and are not guaranteed.

Open Graph, Title, and Meta Description​

These often hold similar text, but they are different tags for different audiences:

TagAudienceNotes
<title>People choosing a search resultInclude your brand. See Title (SEO)
meta name="description"People reading a search snippetSee Meta Description
og:titlePeople seeing a shared linkCan be shorter and friendlier, and often leaves out the brand
og:descriptionPeople seeing a shared linkCan be warmer, or add a hook

They should agree on the topic, but they do not have to match word for word.

Scrapers Do Not Run Your JavaScript​

When an app fetches your link, it usually downloads the HTML and reads it without running scripts. So:

  • Open Graph tags must be in the HTML the server sends, not added later by JavaScript.
  • Single-page apps often fail here. Everyone sees the same default card, whatever page is shared. The fix is server-side rendering, static generation, or a pre-rendering service.
  • Docusaurus builds static HTML for each page, so tags in the head are in the file when it is served. Always check the built page with "view source."

Caching: Why the Preview Will Not Update​

Apps save your preview after the first share. If you change your tags or image afterwards, the old card may keep appearing, sometimes for days.

  • Use a debugger tool to refresh it. For example, Facebook's Sharing Debugger and LinkedIn's Post Inspector let you fetch a page again and clear the old card. (Tool names change, so check the platform's help.)
  • Use a new image address when you change a picture (for example, add a version number to the file name). Apps cache by address.
  • Chat apps cache too, and some offer no way to refresh. Test your page before you share it widely.

Check Your Tags​

http://127.0.0.1:5500/index.html

Check it for real​

  1. "View source" on the live page, and search for og:.
  2. Use the platforms' debuggers, such as the Facebook Sharing Debugger and the LinkedIn Post Inspector, to see what they read.
  3. Share the link privately in a chat app (to yourself) and look at the card.
  4. Check that the image address opens in a private browser window, without being logged in.
  5. Check the file on a phone, on a slow connection.

Open Graph in Docusaurus​

Docusaurus lets you set a social card image for the whole site, in docusaurus.config.js, and uses a page's title and description for the matching tags. You can set a page's own image in its frontmatter (image), or add tags directly with the Head component. The tags end up in the built HTML. Details change between versions, so check the current documentation, and inspect the output.

Good Habits​

  • Add the four essentials to every page.
  • Use a 1200 by 630 image, unique to the page where you can.
  • Use full https addresses.
  • Add og:image:alt and og:site_name.
  • Make og:url match the canonical address.
  • Put the tags in server-rendered HTML.
  • Write titles and descriptions for sharing, not only for search.
  • Test before you share, and refresh with the debuggers.

Open Graph Checklist​

  • og:title, og:type, og:image, and og:url are present
  • Tags use property, and each appears once (except images)
  • The image is JPG, PNG, or WebP, about 1200 by 630, and public
  • All addresses are absolute, and use https
  • og:url matches the canonical address, with no tracking parameters
  • og:image:alt is set
  • Dates use ISO format
  • og:locale is right for the page
  • The tags are in the HTML the server sends
  • A preview was tested in a debugger or a private chat
  • No private data is in any tag

Security and Privacy Notes​

  • Escape everything. If a title or description comes from a database or a user, a stray quote or angle bracket can break your tags, and may inject content. Escape values before you put them in content="...". The builder above does this.
  • Do not leak private pages. If someone shares a link to a private or logged-in page, the app may fetch it, and show the title and image to everyone who sees the card. Do not put private details in the tags of private pages. Use a generic title and image for pages behind a login.
  • Pictures can reveal more than you expect. A share image can include names, faces, and locations. Get permission, and check what is in the picture. Also strip hidden location data (EXIF) from photos.
  • Do not mislead. A card that says one thing while the page says another is deceptive, and could be treated as spam or a scam by the platform.
  • Do not copy another brand's name or look in your tags. This is not legal advice.
  • Apps may fetch your page and image from their own servers. This shows in your logs. It is normal, but if you restrict access by address, allow the platforms you use.
  • Watch for tampering. A hacked page can have its tags changed, so that shares show spam. Check your live tags from time to time.

Global Audience Notes​

  • Set og:locale to the page's language and region (for example fr_FR). For other languages of the same page, add og:locale:alternate tags.
  • Write the tags in the language of the page. Each translation needs its own title, description, and ideally its own image.
  • Text in images is not translated. If your share image has words in it, make a version per language, or keep the image free of text.
  • Right-to-left languages need an image and text that read correctly in the card. Test them.
  • Titles and descriptions get cut at different lengths in different scripts, so check the preview in each language.
  • Platforms differ by country. The app that matters in one country may not exist in another. Open Graph is widely read, but check where your readers share.
  • Slow networks: a large image may not load in time on a poor connection, and the card may appear without it. Keep files small.

Common Mistakes to Avoid​

  1. No Open Graph tags at all.
  2. A relative image address.
  3. A tiny or square image that gets cropped or shrunk.
  4. An SVG as the share image.
  5. The same image on every page.
  6. Using name instead of property.
  7. Tags added only by JavaScript.
  8. og:url with tracking parameters, or different from the canonical.
  9. A private or login-protected image.
  10. A stale preview that is never refreshed.
  11. Missing og:image:alt.
  12. Never testing the card before sharing.

Practice Time​

Try these in your browser and your editor:

  1. Use the builder with website and with article. What changes in the tags?
  2. Enter a small image size and a square one. What do the checks say?
  3. Use the crop lab with each shape. Where would you place a logo so it is never cut off?
  4. Run the checker on the messy page, fix every problem, and run it again.
  5. Create a 1200 by 630 image for a page you built, and keep the title text large and in the middle.
  6. Add the four essential tags to a page, and check them with "view source."
  7. Share a link in a private chat, and look at the card.
  8. Open the Facebook Sharing Debugger or LinkedIn Post Inspector, and fetch your page.
  9. Change an image on a page, and see how long the old one lingers. Then rename the file, and compare.
  10. Bonus: build a page that shows a different Open Graph image for each language version.

Quick Recap​

Click a question to check your answer.

1. What are Open Graph tags for?

They tell apps how to draw a card when your link is shared: its title, description, image, and address. They do not directly affect search ranking.

2. What are the four essential tags?

og:title, og:type, og:image, and og:url.

3. What size should a share image be?

Roughly 1200 by 630 pixels (about 1.91 to 1), in JPG, PNG, or WebP, at a sensible file size, with the key content in the middle. Check each platform's current guidance.

4. Why must the image address be a full address?

The app fetching your page is not on your site, so a relative path such as /img/rye.jpg cannot be found. Use a full https:// address.

5. Why might your Open Graph tags work in "view source" but not in a share?

Apps usually do not run JavaScript. If the tags are added by a script, the app never sees them. They must be in the HTML the server sends.

6. How do you refresh a stale preview?

Use the platform's debugger tool to fetch the page again, or change the image's address. Apps cache by address.

Key Takeaways​

  • Open Graph controls how a shared link looks. It does not boost search rankings by itself.
  • Always set og:title, og:type, og:image, and og:url.
  • Use a wide, public, 1200 by 630 image with full https addresses.
  • Keep og:url equal to the canonical address.
  • Tags must be in server-sent HTML.
  • Previews are cached. Use debuggers, or change the image address.
  • Escape values, and never expose private pages in cards.
  • Test before you share.

Next, learn how X (Twitter) uses these tags and adds its own, in Twitter Cards.