By SitemapFixer Team
Updated April 2026

Gatsby Sitemap: Setup and Configuration Guide

Validate your Gatsby sitemap freeCheck My Sitemap

Gatsby does not generate a sitemap out of the box. You need to add the gatsby-plugin-sitemap plugin, which hooks into the build process and generates your sitemap.xml from all the pages Gatsby knows about. The sitemap is generated at build time and served as a static file.

Installing gatsby-plugin-sitemap

Install the plugin: npm install gatsby-plugin-sitemap. Then add it to gatsby-config.js:

// gatsby-config.js
module.exports = {
siteMetadata: {
siteUrl: 'https://yoursite.com',
} ,
plugins: [
"gatsby-plugin-sitemap",
],
}

After adding the plugin and running gatsby build, your sitemap will be at yoursite.com/sitemap-index.xml. The siteUrl in siteMetadata is required - without it the plugin cannot construct absolute URLs and will fail silently or use relative paths.

Excluding Pages from the Sitemap

To exclude specific pages, use the excludes option in the plugin config:

{
resolve: "gatsby-plugin-sitemap",
options: {
excludes: ["/admin/*", "/thank-you", "/404"],
}
}

Including Dynamic Pages

Pages created programmatically using createPage in gatsby-node.js are automatically included in the sitemap if they are in the pages query. For pages sourced from a CMS like Contentful or Sanity, the plugin queries all pages via GraphQL and includes them. If your dynamic pages are missing from the sitemap, check that the GraphQL query in the plugin config includes those page types. You may need to customize the query option to explicitly include CMS-sourced pages.

Common Gatsby Sitemap Problems

Sitemap only generated in production build: gatsby-plugin-sitemap only runs during gatsby build, not gatsby develop. You cannot test the sitemap locally in dev mode. Run gatsby build and gatsby serve to check the sitemap locally.

Wrong siteUrl: If your siteUrl in gatsby-config.js points to localhost or a staging URL, your sitemap will contain the wrong base URL. Set it to your production domain and use environment variables for local development.

Plugin version mismatch: gatsby-plugin-sitemap v5+ (for Gatsby v4+) has a different API than earlier versions. If you upgraded Gatsby, check the plugin documentation for API changes - the output file changed from sitemap.xml to sitemap-index.xml in v5.

Validate your Gatsby sitemap
Free - checks every URL in 60 seconds
Check My Sitemap Free

Related Guides