https://github.com/ainsleyclark/payload-sitemap-plugin
Sitemap Plugin for PayloadCMS
https://github.com/ainsleyclark/payload-sitemap-plugin
cms payload payload-plugin payloadcms plugin
Last synced: about 1 month ago
JSON representation
Sitemap Plugin for PayloadCMS
- Host: GitHub
- URL: https://github.com/ainsleyclark/payload-sitemap-plugin
- Owner: ainsleyclark
- License: mit
- Created: 2025-03-13T17:20:45.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-09-26T10:40:29.000Z (8 months ago)
- Last Synced: 2026-02-15T11:58:34.925Z (4 months ago)
- Topics: cms, payload, payload-plugin, payloadcms, plugin
- Language: TypeScript
- Homepage:
- Size: 245 KB
- Stars: 44
- Watchers: 1
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yaml
- License: LICENSE
Awesome Lists containing this project
README
Payload Sitemap Plugin
GoLang client library & SDK for Payload CMS
[](https://opensource.org/licenses/MIT)
[](https://payloadcms.com)
[](https://www.npmjs.com/package/payload-sitemap-plugin)
[](https://github.com/ainsleyclark/payload-sitemap-plugin/actions/workflows/test.yaml)
[](https://github.com/ainsleyclark/payload-sitemap-plugin/actions/workflows/lint.yaml)
[](https://ainsley.dev)
[](https://twitter.com/ainsleydev)
## 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
```bash
pnpm i payload-sitemap-plugin
```
## Quick Start
```ts
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](https://developers.google.com/search/docs/advanced/robots/create-robots-txt).
## 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](https://payloadcms.com/docs/jobs-queue/queues#executing-jobs) 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: ``
- 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](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.