Complete configuration options for customizing gatsby-plugin-sitemap behavior, including output location, entry limits, custom queries, and filtering options.
/**
* Folder path where sitemaps are stored in public directory
* @default '/'
*/
output?: string;Usage Example:
// gatsby-config.js
{
resolve: 'gatsby-plugin-sitemap',
options: {
output: '/sitemaps', // Generates files in public/sitemaps/
}
}/**
* Whether to populate the <head> of your site with a link to the sitemap
* @default true
*/
createLinkInHead?: boolean;/**
* Number of entries per sitemap file. Creates sitemap index and multiple
* sitemaps if exceeded
* @default 45000
*/
entryLimit?: number;/**
* Array of paths to exclude from sitemap. Supports glob patterns via minimatch.
* Can contain non-string values for custom filtering (requires custom filterPages function)
* @default []
*/
excludes?: any[];Usage Example:
{
resolve: 'gatsby-plugin-sitemap',
options: {
excludes: [
'/admin/*',
'/private/**',
'/dev-404-page',
'/404',
'/offline-plugin-app-shell-fallback'
]
}
}/**
* GraphQL query for data needed to generate sitemap. Must include site URL data.
* If customized, may require custom resolvePagePath, resolvePages, or resolveSiteUrl functions
* @default Standard query for site.siteMetadata.siteUrl and allSitePage.nodes
*/
query?: string;Default Query:
const defaultQuery = `{
site {
siteMetadata {
siteUrl
}
}
allSitePage {
nodes {
path
}
}
}`;Custom Query Example:
{
resolve: 'gatsby-plugin-sitemap',
options: {
query: `
{
allSitePage {
edges {
node {
path
}
}
}
allWpContentNode(filter: {nodeType: {in: ["Post", "Page"]}}) {
nodes {
... on WpPost {
uri
modifiedGmt
}
... on WpPage {
uri
modifiedGmt
}
}
}
}
`,
resolveSiteUrl: () => 'https://example.com',
resolvePages: ({ allSitePage: { edges }, allWpContentNode: { nodes } }) => {
const wpNodeMap = nodes.reduce((acc, node) => {
acc[node.uri] = node;
return acc;
}, {});
return edges.map(edge => ({
...edge.node,
...wpNodeMap[edge.node.path]
}));
}
}
}/**
* Function to extract site URL from GraphQL query data.
* Can be sync or async
* @param data - Results of the GraphQL query
* @returns Site URL string
* @throws Error if site URL cannot be resolved
*/
resolveSiteUrl?: (data: any) => string | Promise<string>;/**
* Function to extract page path from page object
* @param page - Page object from resolvePages result
* @returns Page path without domain or protocol
* @throws Error if path cannot be resolved
*/
resolvePagePath?: (page: any) => string;/**
* Function to extract pages array from GraphQL query data.
* Can be sync or async. Use for merging multiple data sources
* @param data - Results of the GraphQL query
* @returns Array of page objects
* @throws Error if pages cannot be resolved
*/
resolvePages?: (data: any) => any[] | Promise<any[]>;/**
* Custom filtering function for pages based on exclude patterns.
* Called for each page/exclude combination
* @param page - Page object containing path
* @param excludedRoute - Item from excludes array
* @param tools - Filtering utilities
* @returns true to exclude page, false to include
*/
filterPages?: (page: any, excludedRoute: any, tools: FilterTools) => boolean;
interface FilterTools {
minimatch: (path: string, pattern: string) => boolean;
withoutTrailingSlash: (path: string) => string;
resolvePagePath: (page: any) => string;
}/**
* Function to convert page objects into sitemap entries.
* Can be sync or async
* @param page - Page object from filtered pages
* @param tools - Serialization utilities
* @returns Sitemap entry object with url and optional properties
*/
serialize?: (page: any, tools: SerializeTools) => SitemapEntry | Promise<SitemapEntry>;
interface SerializeTools {
resolvePagePath: (page: any) => string;
}
interface SitemapEntry {
url: string;
lastmod?: string;
changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
priority?: number;
}Serialize Example:
{
resolve: 'gatsby-plugin-sitemap',
options: {
serialize: ({ path, modifiedGmt }) => ({
url: path,
lastmod: modifiedGmt,
// Note: Google ignores changefreq and priority
})
}
}// gatsby-config.js
const siteUrl = process.env.URL || 'https://fallback.net';
module.exports = {
plugins: [
{
resolve: 'gatsby-plugin-sitemap',
options: {
output: '/',
createLinkInHead: true,
entryLimit: 45000,
excludes: ['/admin/*', '/private/**'],
query: `
{
allSitePage {
nodes {
path
}
}
allWpContentNode(filter: {nodeType: {in: ["Post", "Page"]}}) {
nodes {
... on WpPost {
uri
modifiedGmt
}
... on WpPage {
uri
modifiedGmt
}
}
}
}
`,
resolveSiteUrl: () => siteUrl,
resolvePages: ({ allSitePage: { nodes: allPages }, allWpContentNode: { nodes: allWpNodes } }) => {
const wpNodeMap = allWpNodes.reduce((acc, node) => {
const { uri } = node;
acc[uri] = node;
return acc;
}, {});
return allPages.map(page => ({ ...page, ...wpNodeMap[page.path] }));
},
serialize: ({ path, modifiedGmt }) => ({
url: path,
lastmod: modifiedGmt,
}),
},
},
],
};