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.