Payload Sitemap Plugin

GoLang client library & SDK for Payload CMS

Introduction

This plugin provides an automatic way of syncing your Payload collections into a generated Sitemap.

• ✅ Generates XML Sitemaps directly from your Payload collections.
• ✅ Configurable cache system and endpoint to regenerate the sitemap.
• ✅ Extensible with fields and config.
• ✅ Add custom routes to your sitemap.

Installation

pnpm i payload-sitemap-plugin 

Quick Start

import { sitemapPlugin } from 'payload-sitemap-plugin';

export default buildConfig({
	plugins: [
		sitemapPlugin({
			hostname: 'https://example.com',
			cache: true,
			defaultPriority: 0.5,
			includeDrafts: true,
			includeHomepage: true,
			collections: {
				posts: {
					priority: 0.8,
					changeFreq: 'weekly',
					includeDrafts: false,
					fieldOverrides: ({ defaultFields }) => [
						...defaultFields,
						{
							name: 'customSEO',
							type: 'text',
							label: 'Custom SEO Field',
						},
					],
				},
				pages: true
			},
			generateURL: ({ doc }) => `/${doc.slug}`,
			customRoutes: [
				{
					loc: '/about',
					priority: 0.7,
					lastMod: new Date('2024-01-01')
				}
			],
			globalOverrides: {
				fields: ({ defaultFields }) => [
					...defaultFields,
					{
						name: 'extraSetting',
						type: 'text',
						label: 'Extra Setting',
					},
				],
			},
		})
	]
});

Robots.txt

To make sure search engines are able to find the sitemap XML create a robots.txt file in the front-end of your website and add the following line:

Sitemap: https://your-payload-domain.com/api/plugin-sitemap/sitemap/index.xml

Read more about the robots.txt file here.

Fields

Two fields are added to the collections that are specified enabling easy customisation of each document in the sitemap.

• excludeFromSitemap - A checkbox field to specify whether a document should be excluded from the sitemap.
• sitemapPriority - A select field to define the priority of a document in the sitemap, with values ranging from 0 to 1.

Caching

If caching is enabled, a sitemap global is used to store the results of sitemap generation once it has been created. This global contains a JSON representation of the sitemap, and when it was last modified.

The user is responsible for re-generating sitemaps. Refer to the regenerate endpoint below for instructions on how to manually trigger sitemap regeneration.

Visit the documentation for more details.

Endpoints

Endpoint	Description	Method
/api/plugin-sitemap/sitemap/index.xml	The generated sitemap XML file.	GET
/api/plugin-sitemap/regenerate	Endpoint to regenerate the sitemap.	POST

Config

Option	Default	Description
hostname	Required	Base URL for absolute links. This is required for generating fully qualified URLs in the sitemap.
cache	false	Cache configuration for the sitemap. Can be a boolean (enable/disable) or an object with duration and enabled flags.
cache.duration	86400 (1 day)	Cache duration in seconds for storing the generated sitemap.
cache.enabled	false	If true, caching of the generated sitemap will be enabled.
collections	{}	Collection-specific configuration for the sitemap. Each key corresponds to a collection slug, and custom options can be provided for that collection.
collections.[key]	-	Settings for a specific collection in the sitemap. If set to true, it includes all documents in that collection with default settings.
collections.[key].changeFreq	-	Frequency at which pages in this collection are expected to change. Can be overridden for each document.
collections.[key].includeDrafts	false	If true, drafts for this collection will be included in the sitemap.
collections.[key].lastModField	-	Custom field to determine the last modified date (lastmod) for documents in the collection.
collections.[key].priority	-	Default priority for documents in this collection. Can be between 0.0 and 1.0.
collections.[key].fieldOverrides	-	Function to override or extend the default fields (sitemapPriority and excludeFromSitemap) for this collection. Returns a new array of fields.
customRoutes	-	Custom routes to include in the sitemap with their own configuration (change frequency, last modified date, priority).
defaultPriority	0.5	Default priority for all documents in the sitemap. Values range from 0.0 (lowest) to 1.0 (highest).
disabled	false	If set to true, disables the sitemap plugin.
generateURL	-	Custom function to generate URLs for documents in this collection.
includeDrafts	false	If true, includes drafts in the sitemap. This is overridden by individual collection settings.
includeHomepage	true	If true, includes a default / entry in the sitemap.
globalOverrides	true	Function to override or extend fields on the sitemap global used for caching. Returns a new array of fields.

TODO

• Add localisation, ability to specify alternate pages: <xhtml:link rel="alternate">
• Allow limit and sitemaps greater than 45,000.

Contributing

Contributions are welcome! If you find any bugs or have suggestions for improvement, please open an issue or submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Trademark

ainsley.dev and the ainsley.dev logo are either registered trademarks or trademarks of ainsley.dev LTD in the United Kingdom and/or other countries. All other trademarks are the property of their respective owners.