Sitemaps and feeds are the quiet plumbing of a Gatsby site. gatsby-plugin-sitemap and gatsby-plugin-feed work until they don't: a plugin falls behind a Gatsby release, lastmod is missing or set to the build time on every page, noindex pages leak in, or the site URL differs between preview and production. Since both files are just XML built from data you already have, generating them yourself is small and easy to reason about.
This tutorial shows a dependency-free approach for Gatsby 5.
1. Decide the source of truth
Before writing code, decide three things:
- One canonical origin. Read it from an environment variable, not from
siteMetadata, so previews never emit production URLs. - What is indexable. Keep a boolean such as
frontmatter.noindexor adraftflag, and exclude those pages from both files. - A real modified date. Use a
updatedfrontmatter field or the file's git commit date. Never use the build time: crawlers learn to ignorelastmodif it always changes.
2. Expose the data in the schema
In gatsby-node.js, make the fields explicit so a missing value does not break the query:
exports.createSchemaCustomization = ({ actions }) => {
actions.createTypes(`
type MarkdownRemarkFrontmatter {
title: String
date: Date @dateformat
updated: Date @dateformat
noindex: Boolean
}
`)
}
3. Write the files in onPostBuild
onPostBuild runs after pages are built, so the output lands in public/ next to everything else.
const fs = require('fs')
const path = require('path')
const esc = (s) =>
String(s).replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>')
exports.onPostBuild = async ({ graphql, reporter }) => {
const origin = (process.env.SITE_ORIGIN || '').replace(/\/$/, '')
if (!origin) {
reporter.warn('SITE_ORIGIN not set; skipping sitemap and feed')
return
}
const { data, errors } = await graphql(`{
allMarkdownRemark(sort: { frontmatter: { date: DESC } }) {
nodes {
fields { slug }
excerpt(pruneLength: 240)
frontmatter { title date updated noindex }
}
}
}`)
if (errors) throw errors
const nodes = data.allMarkdownRemark.nodes.filter((n) => !n.frontmatter.noindex)
const urls = nodes.map((n) => {
const lastmod = n.frontmatter.updated || n.frontmatter.date
return ` <url><loc>${origin}${n.fields.slug}</loc>` +
(lastmod ? `<lastmod>${new Date(lastmod).toISOString()}</lastmod>` : '') +
`</url>`
})
fs.writeFileSync(
path.join('public', 'sitemap.xml'),
`<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls.join('\n')}\n</urlset>\n`
)
const items = nodes.slice(0, 20).map((n) =>
` <item><title>${esc(n.frontmatter.title)}</title>` +
`<link>${origin}${n.fields.slug}</link>` +
`<guid isPermaLink="true">${origin}${n.fields.slug}</guid>` +
`<pubDate>${new Date(n.frontmatter.date).toUTCString()}</pubDate>` +
`<description>${esc(n.excerpt)}</description></item>`
)
fs.writeFileSync(
path.join('public', 'rss.xml'),
`<?xml version="1.0" encoding="UTF-8"?>\n<rss version="2.0"><channel>\n <title>Site feed</title><link>${origin}</link><description>Latest posts</description>\n${items.join('\n')}\n</channel></rss>\n`
)
reporter.info(`Wrote sitemap.xml (${urls.length} URLs) and rss.xml`)
}
Pages that are not Markdown (landing pages built from src/pages) need adding too. Append them from a static list, or query allSitePage and filter by path prefix.
4. Make them discoverable
Add the feed to the document head with the Head API, and point to the sitemap from static/robots.txt:
export const Head = () => (
<link rel="alternate" type="application/rss+xml" title="Feed" href="/rss.xml" />
)
User-agent: *
Allow: /
Sitemap: https://example.com/sitemap.xml
5. Trailing slashes must match
If your gatsby-config.js sets trailingSlash: 'always', every <loc> must end in a slash. A sitemap that disagrees with the canonical tag produces redirect hops that Search Console reports as warnings. Normalise in one helper and use it for the sitemap, feed, and canonical tag.
6. Verify after deploy
Add a check to CI that runs against the built public/ folder:
const xml = require('fs').readFileSync('public/sitemap.xml', 'utf8')
const locs = [...xml.matchAll(/<loc>(.*?)<\/loc>/g)].map((m) => m[1])
if (!locs.length) throw new Error('empty sitemap')
if (locs.some((l) => !l.startsWith(process.env.SITE_ORIGIN))) throw new Error('wrong origin')
if (new Set(locs).size !== locs.length) throw new Error('duplicate URLs')
Then, after deploy, fetch a handful of sitemap URLs and confirm each returns 200 with no redirect and no noindex header. Submit the sitemap once in Search Console and Bing Webmaster Tools.
Common mistakes
- Build-time
lastmodon every URL. Use real dates or omit the field. - Preview origins in production files. Always read the origin from the environment.
- Unescaped
&in titles. It breaks the feed XML; escape as above. - Over 50,000 URLs. Split into a sitemap index; this is rare but real for large catalogs.
Need a hand?
If your Gatsby site has indexing problems or relies on plugins that are no longer maintained, our team can audit and fix it. Get in touch through our contact page.