+1 (415) 779-8456

Sitemaps and RSS on Gatsby 5: Generate Them Yourself in onPostBuild

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.noindex or a draft flag, and exclude those pages from both files.
  • A real modified date. Use a updated frontmatter field or the file's git commit date. Never use the build time: crawlers learn to ignore lastmod if 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, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')

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 lastmod on 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.