Gatsby SEO: the Head API, the sitemap plugin, and what Gatsby's own site says about its status today

Gatsby SEO starts with static HTML: Gatsby builds your pages ahead of time, and its docs say metadata added through the Gatsby Head API is server-rendered into those static pages. To finish the job you set siteUrl in siteMetadata, build one reusable SEO component used through the Head export on every page, add gatsby-plugin-sitemap, and add JSON-LD where it helps. Before you invest, also check the framework's status as Gatsby itself states it: on 22 October 2026 its version support page listed Gatsby 5 as the active long-term support version, its latest release notes were for 5.16 (January 2026), and its site carried a banner offering Gatsby Cloud customers migration to Netlify. This page covers each step from Gatsby's own documentation, read that day.

Gatsby's status today, from its own site

A framework decision is an SEO decision, because you will live with its rendering and plugins for years. Here is what gatsbyjs.com said on 22 October 2026:

• Version support. The version support page lists Gatsby 5 as "Active Long-term support" since 8 November 2022. Gatsby 4 was in maintenance until Q4 2023, and versions 2 and 3 are unsupported. The page says only the active version receives new features.
• Latest release. The newest release notes are for gatsby@5.16.0, dated January 2026, which added React 19 and Node.js 24 support. The npm registry showed 5.16.1, published 10 February 2026, as the latest version.
• Hosting. Every page on gatsbyjs.com carried the line "Netlify announces the next evolution of Gatsby Cloud", and the home page said Netlify is offering Gatsby Cloud customers migration paths to Netlify.

The project's GitHub repository was not archived on the same day. So the fair summary is: Gatsby 5 is supported and still receiving releases, at a slower pace than the newer frameworks. If you are starting a new site, compare it with the alternatives in our guide to static content generators. If you already run Gatsby, the steps below are what matters.

Step 1: set siteMetadata and siteUrl

Gatsby's guide to adding an SEO component says the siteMetadata section of gatsby-config is available in the GraphQL data layer, and that it is best practice to keep your site metadata there. It says siteUrl should be the URL of your deployed production domain, so later tags can point to absolute URLs.

// gatsby-config.js
module.exports = { siteMetadata: { title: 'Example', description: 'What this site is about, in one sentence.', siteUrl: 'https://www.example.com', image: '/social-card.png', }, plugins: ['gatsby-plugin-sitemap'],
}

Use the exact host you want indexed, with or without www, so canonicals and the sitemap match it.

Step 2: one SEO component, used through the Head export

The guide requires gatsby@4.19.0 or later, because it uses the Gatsby Head API. The pattern has three parts: a useSiteMetadata hook that reads siteMetadata with useStaticQuery; an SEO component that takes title, description, pathname and children as props and falls back to the site values; and a Head export on each page that renders it.

// src/pages/about.jsx
import * as React from 'react'
import { SEO } from '../components/seo' export default function AboutPage() { return <main>...</main>
} export const Head = () => ( <SEO title="About us" pathname="/about/" />
)

Rules from the Gatsby Head reference that cause most mistakes:

• The Head export only works in a page or a page template used with createPage, not in an ordinary component.
• Duplicate tags are settled by id. Give a tag an id and, if two tags share it, the last one wins. Use this when a page overrides a site-wide tag.
• The pathname prop is relative, so the component must join it to siteUrl to build an absolute canonical or Open Graph URL.
• Data scripts belong in Head. JSON-LD <script> tags can go in the Head function, while dynamic scripts are better loaded with the Gatsby Script component.

The guide recommends a prop || fallback pattern so no value is ever undefined. An empty description is worse than a generic one. Our guide to meta descriptions has worked examples.

Step 3: add gatsby-plugin-sitemap

The official sitemap plugin (version 6.16.0 on npm that day) needs little configuration once siteUrl is set. Its documentation says:

• It writes sitemap-index.xml at the site root, plus a new sitemap-X.xml file for every 45,000 URLs. Under that number you get only sitemap-0.xml.
• It only generates output in production mode. To test, run gatsby build and then gatsby serve.
• The excludes option takes paths, with glob matching, to leave out pages such as thank-you pages.
• The pages /dev-404-page, /404 and /offline-plugin-app-shell-fallback are always excluded.
• If you do not use siteMetadata.siteUrl, you must supply a resolveSiteUrl function.

Submit sitemap-index.xml in Search Console, as the plugin docs suggest, and add a Sitemap: line to your robots.txt.

Step 4: structured data

Gatsby's SEO guide includes a JSON-LD example and points you to Google's Rich Results Test during development, then to the rich result status reports in Search Console after deployment. Build the JSON-LD from the same props as the SEO component so the title and URL in the markup always match the page. Our page on schema validators explains which checker to use for which markup.

Step 5: keep content in the static HTML

Gatsby's home page lists SSR, DSG (deferred static generation) and cloud functions as options beyond the default static build. Static and server-rendered pages both send full HTML. The risk is content that only appears after the page loads, for example text fetched in the browser with useEffect. Google's JavaScript SEO guide says server-side or pre-rendering "is still a great idea" because not all bots can run JavaScript, so anything you want indexed should come through Gatsby's data layer at build time or through SSR.

To check, fetch a page with curl and search the response for your heading, description and body text. For a broader view of React rendering choices, see our React SEO guide.

Questions about Gatsby SEO

Is Gatsby still good for SEO?

Yes. It builds static HTML with server-rendered metadata, which search engines read easily. On 22 October 2026, Gatsby's site listed version 5 as actively supported, with its last feature release in January 2026, so weigh that pace when choosing a framework for a new site.

Should I still use react-helmet with Gatsby?

Gatsby's current SEO guide uses the built-in Head API, available from gatsby@4.19.0. New code should follow that guide, and older Helmet code can move to Head exports page by page.

Why is my Gatsby sitemap missing?

The plugin only generates output in production mode. Run gatsby build and check for sitemap-index.xml in the build output, and make sure siteUrl is set.

Can I add JSON-LD in Gatsby?

Yes. Gatsby's docs say data block scripts such as application/ld+json can go in the Head function of a page or template.

Is Gatsby maintained?

On 22 October 2026, gatsbyjs.com showed Gatsby 5 in active long-term support, the npm registry showed a release from February 2026, and the GitHub repository was active and not archived.

Static HTML reads well to assistants too

A Gatsby page that ships its full text in static HTML is easy for an AI assistant to fetch and quote. Whether that assistant names your business when a buyer asks it to recommend one is a separate outcome, and none of your SEO reports show it. Measuring which assistants name you, and from which sources, is the new category AI Knows Us works in.