How To Build a Custom Sitemap for Your Gatsby.js Site

Published on December 12, 2019

Maedah Batool

How To Build a Custom Sitemap for Your Gatsby.js Site

While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.

When you require an easy to deploy setup, it is possible to build static sites with React using Gatsby.js. These provide good speed and smooth developer experience. Gatsby has been consistently growing with developers using it for blog, marketing, and e-commerce sites.

Every time, you build a site you can help search engine’s crawlers to improve organic search rankings. You have to ensure that search engines like Google can understand your site’s architecture and index it intelligently. You can do all that by including a sitemap.xml file at the root of your site.

Gatsby homepage

With the growing popularity of Gatsby.js and JAMstack sites, in this tutorial you’ll automatically generate a custom XML sitemap file in your Gatsby powered websites.

XML Sitemap

A website is composed of several web pages like About, Contact, Blog, Subscribe, etc. A sitemap file maintains a list of all these pages to tell search engines like Google about the organization of your site content. Search engine web crawlers like Googlebot read through this file and crawl your site intelligently.

Back in the early days of the web, HTML sitemap which was a manually generated bullet-list were in trend. But, owing to their popularity and importance, sitemaps are published in XML format instead of HTML since their target audience is search engines and not people.

So, an XML sitemap file communicates with the search engines about all the pages that exist on your website.

Importance of Adding a Sitemap File

Considering Search Engine Optimization (SEO), sitemaps are very important. However, they do not affect your search rankings. Instead, if there’s a web page which is not indexed, then sitemap tells the search engines about that page to get it appropriately indexed.

Sitemaps are equally important for both new and old sites. Especially if your site is relatively new then it is recommended to add one since it is difficult for search engines to find posts and pages of a new site. You want to make the search engine’s job as easy as possible to get the most out of it.

You will find sitemap.xml files on most websites. This helps the search engine bots to keep a tab on various updates and basically everything that goes about on a site that should be indexed.

Adding a Sitemap in Gatsby

One key highlight of Gatsby is its growing collection of plugins that implement Gatsby API through simple NPM packages.

Now, to create a sitemap you don’t have to bother writing several lines of code. There is a Gatsby plugin to generate the sitemap file called the gatsby-plugin-sitemap.

You’ll need to have a Gatsby site up and running before continuing with this tutorial.


To install the gatsby-plugin-sitemap package, run the following command in the root folder:

  1. npm install --save gatsby-plugin-sitemap

Using the Plugin: gatsby-plugin-sitemap

Now the plugin is successfully installed, it’s time to add this plugin to the gatsby-config.js file. A quick reminder to those who are new to Gatsby; that inside gatsby-config.js file you’ll find all the site configuration options which are placed in the root folder.

One of these configuration options is for plugins. Here you’ll find an array of plugins that implement Gatsby APIs. Some plugins are listed by name, while others may take options as well — and gatsby-plugin-sitemap carries options as well.

So, add the following lines of code in your gatsby-config.js file:

module.exports = {
  siteMetadata: {
    title: 'Your Site Title',
    siteUrl: 'https://yoursite.com',
  plugins: ['gatsby-plugin-sitemap'],

Make sure that inside siteMetadata you change the title and siteUrl according to your project details.

Generating A Sitemap File

To create a sitemap you need to generate a production build and start the server. In your terminal type the following command and hit ENTER.

  1. npm run build

Wait for a few seconds and you get a working sitemap with Gatsby.

Gif of the output from the  command

By default, the sitemap is generated in the root of your website which is a folder called public . When you deploy your site, you can access it through /sitemap.xml and it will display all of your site’s pages that are currently accessible to users.

You can access the sitemap of your site with the following URL:


The gatsby-plugin-sitemap plugin supports advanced custom options so this default functionality can be changed accordingly. Let’s dig a little deep with these options.

Advanced Options for gatsby-plugin-sitemap

The gatsby-plugin-sitemap supports different advanced options that you can customize to gain more control over your sitemap.xml files. Let’s take a look at some of these:

  • output: The default file name is sitemap.xml you can use the output option to change the name of the output file. For example with output: '/some-other-sitemap.xml', the URL now becomes https://your-domain/some-other-sitemap.xml.
  • exclude: This option can help you exclude any links from the sitemap for whatever reasons.
  • query: Custom GraphQL query to fetch info like siteMetadata, siteURL, allSitePage, etc.

There are a couple of other handy options as well for sitemapSize and sitemap index. You can visit the official plugin repo for more info here.

Customized Options Example

For example, in this tutorial, we’re customizing the plugin’s options to generate data of our choice. Here, we’ve customized the GraphQL query:

      resolve: `gatsby-plugin-sitemap`,
      options: {
        query: `{
          site {
            siteMetadata {
          allSitePage {
            edges {
              node {
          allMarkdownRemark {
            edges {
              node {
                fields {
        serialize: ({ site, allSitePage, allMarkdownRemark }) => {
          let pages = []
          allSitePage.edges.map(edge => {
              url: site.siteMetadata.siteUrlNoSlash + edge.node.path,
              changefreq: `daily`,
              priority: 0.7,
          allMarkdownRemark.edges.map(edge => {
              url: `${site.siteMetadata.siteUrlNoSlash}/${
              changefreq: `daily`,
              priority: 0.7,

          return pages

Here, we use the query option to fetch data for our site that includes info about siteMetadata and siteUrlNoSlash. Further, we query the allSitePage to get all site pages URL paths that is to retrieve path property for each graph node through all edges. And finally, we use the allMarkdownRemark that reads files written in markdown and then converts them into HTML pages. Here we are getting the slug info for each markdown post from inside the field property.

Towards the end, we’ve called the serialize function to map data that is fetched for allSitePage and allMarkdownRemark. Each returns a page URL with changefreq: 'daily' and a priority: 0.7.

This was one demonstration of playing around with custom options for the gatsby-plugin-sitemap, you can do it according to the requirement of your project.

You can access a live sitemap demo for Gatsby.js here.

Gif showing the sitemap.xml


Generating sitemaps can be more manageable with Gatsby.js. The result of creating a sitemap.xml file with gatsby-plugin-sitemap shows the developer experience of using Gatsby.js is improving.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

About the authors
Default avatar
Maedah Batool


Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
Leave a comment

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel