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
siteMetadata.siteUrlis the production domain, with no trailing slash if paths start with/.- Every page and
createPagetemplate exportsHead; no component does. og:imagejoinssiteUrland the path, and starts withhttps://.- Only one place writes
og:imageper page; remove oldreact-helmettags after moving to Head. - 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.