payload-sitemap-plugin - Payload CMS Plugin

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.