Guide

Astro Open Graph image

Astro has no share-image setting. You write the tags in the <head> of a layout and pass each page's image as a prop. The usual break is a built page whose og:image says localhost, because site is not set in astro.config.mjs.

Set site first

The configuration reference describes site as your final, deployed URL, used for the sitemap and canonical URLs, and strongly recommends setting it.

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://www.example.com',
});

This line matters more for share cards than for anything else. The API reference says Astro.url is a localhost URL in dev, prerendered routes get a URL based on site and base at build time, and if site is not configured, prerendered pages receive a localhost URL during builds as well. An og:image built from Astro.url then points at localhost on the live site, and no app can fetch it. Astro.site is undefined when site is unset.

Tags in a base layout

---
// src/layouts/Base.astro
const { title, description, image = '/og/default.png' } = Astro.props;
const canonical = new URL(Astro.url.pathname, Astro.site);
const ogImage = new URL(image, Astro.site);
---
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>{title}</title>
    <meta name="description" content={description} />
    <link rel="canonical" href={canonical} />
    <meta property="og:title" content={title} />
    <meta property="og:description" content={description} />
    <meta property="og:url" content={canonical} />
    <meta property="og:image" content={ogImage} />
    <meta name="twitter:card" content="summary_large_image" />
  </head>
  <body><slot /></body>
</html>

The API reference uses the same pattern: new URL(Astro.url.pathname, Astro.site) for a canonical URL. Use property="og:image", not name; some apps ignore the name form. og:url vs canonical covers why both should match.

Each page passes its image

---
// src/pages/blog/my-post.astro
import Base from '../../layouts/Base.astro';
---
<Base title="My post" description="One line about it." image="/og/my-post.png">
  <h1>My post</h1>
</Base>

For Markdown or content collection posts, put image in the frontmatter and pass it through the same way. Pages that pass nothing get the default.

Where the image file lives

The images guide separates src/ from public/. Files in public/ are served as they are, at a fixed path, which suits a share image: public/og/my-post.png is /og/my-post.png. An image imported from src/ is processed and gets a generated file name, so pass its src into new URL(..., Astro.site) rather than guessing the path. Keep the image 1200 × 630 PNG or JPEG; Open Graph image format lists what each app accepts.

Read the built HTML

npm run build
grep -o '<meta property="og:image"[^>]*>' dist/blog/my-post/index.html

If the value starts with http://localhost, site is missing. After deploying, check the live page and paste the URL into the form above.

Checklist

  1. site in astro.config.mjs is the deployed URL.
  2. One base layout writes the share tags; pages pass props instead of adding a second og:image.
  3. og:image is built with new URL(image, Astro.site) and starts with https://.
  4. The built HTML in dist/ has no localhost in any share tag.
  5. After a change, apps that cached the old card get a refresh: see Clear Open Graph cache.

Other frameworks: Next.js, Gatsby, Nuxt, and SvelteKit.

FAQ

Where do the tags go?

In the <head> of a base layout, from props each page passes in.

Why localhost in og:image?

site is missing from astro.config.mjs, so built pages use a localhost URL. Set it to the deployed site.

Do I need an integration?

No. A few <meta> lines in the layout are enough. Astro writes them into each page's HTML at build time.

What does a CardScope check cost?

A free check shows previews for X, LinkedIn, Slack, Discord, iMessage, Bluesky, Threads, Mastodon, WhatsApp, Telegram, and Microsoft Teams, plus the fix checklist. Pro is $19 once via Stripe Checkout, not a subscription: unlimited checks, a 50-page site audit with a CSV, share links, and PNG export. No account. A sample report shows a full result. A free audit checks the first 3 pages of a site and lists the rest. We parse HTML in memory and discard it — we do not store the page.