Guide

Gatsby Open Graph image

Gatsby writes share tags from a Head export on each page or template, usually through a small SEO component. Cards break when the image path is relative because siteUrl is missing, or when Head is exported from a component instead of a page.

siteUrl in gatsby-config

The SEO component guide puts site metadata in gatsby-config and says siteUrl should be the URL of your deployed target, such as the production domain, so meta tags can point to absolute URLs.

// gatsby-config.js
module.exports = {
  siteMetadata: {
    title: 'Example',
    description: 'One line about the site.',
    siteUrl: 'https://www.example.com',
    image: '/og/default.png',
  },
};

An SEO component

// src/components/seo.jsx
import React from 'react';
import { useSiteMetadata } from '../hooks/use-site-metadata';

export const Seo = ({ title, description, image, pathname, children }) => {
  const site = useSiteMetadata();
  const seo = {
    title: title || site.title,
    description: description || site.description,
    image: `${site.siteUrl}${image || site.image}`,
    url: `${site.siteUrl}${pathname || ''}`,
  };
  return (
    <>
      <title>{seo.title}</title>
      <meta name="description" content={seo.description} />
      <meta property="og:title" content={seo.title} />
      <meta property="og:description" content={seo.description} />
      <meta property="og:url" content={seo.url} />
      <meta property="og:image" content={seo.image} />
      <meta name="twitter:card" content="summary_large_image" />
      {children}
    </>
  );
};

The guide builds the same kind of component with a useSiteMetadata hook that reads siteMetadata through a static query. The image line joins siteUrl and the path, so the tag carries a full https:// URL. Absolute og:image URL lists the apps that drop relative paths.

Export Head from each page and template

The Gatsby Head reference says the API was added in gatsby@4.19.0, and that a named Head export sets a page's metadata. Its usage notes add the rule that trips people up: Head can only be defined in a page, including templates for createPage, not in a component. Head contents are cleared when the page unmounts, so each page defines what it needs.

// src/templates/post.jsx
export const Head = ({ data, location }) => (
  <Seo
    title={data.markdownRemark.frontmatter.title}
    description={data.markdownRemark.excerpt}
    image={data.markdownRemark.frontmatter.ogImage}
    pathname={location.pathname}
  />
);

Head receives location, params, data from the page query, and pageContext, so a post template can read its image from frontmatter. Put share images in static/ so /og/my-post.png stays a fixed path, and keep them 1200 × 630; see Open Graph image size.

Read the built HTML

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

gatsby develop serves on localhost, which no app can fetch. Check the built file or a deployed URL, then paste the live URL into the form above.

Checklist

  1. siteMetadata.siteUrl is the production domain, with no trailing slash if paths start with /.
  2. Every page and createPage template exports Head; no component does.
  3. og:image joins siteUrl and the path, and starts with https://.
  4. Only one place writes og:image per page; remove old react-helmet tags after moving to Head.
  5. After a change, apps that cached the old card get a refresh: see Clear Open Graph cache.

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

FAQ

Where do the tags go?

In a Head export on each page or template, usually returning an <Seo /> component.

Why are no tags added?

Head was exported from a component. It only works in pages and createPage templates.

Do I still need react-helmet?

Not on Gatsby 4.19.0 or later. The built-in Head API replaces it, and the Gatsby docs list it as smaller and faster.

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.