Proposal: createSitemapItems hook - a sitemap equivalent to createFeedItems

[johnnyreilly]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

There is already a way for users to control their RSS / Atom / JSON feeds with the createFeedItems hook.

Wouldn't it be great if there was an equivalent API for sitemap?

This idea comes from the comment @slorber made here: #2604 (comment)

we could do like the blog plugin and let users provide a createSitemapItem hook to add extra attributes if they want to? 🤷‍♂️

Has this been requested on Canny?

No

Motivation

I presently mutate my sitemap manually on each build as a post processing step. I've written about it here and I have historically done this for two reasons:

1. To add lastmod to sitemap entries (something that is no longer necessary as of 3.2)
2. To trim pagination, tags pages and programmatically determined canonicals from the sitemap - this is still necessary

If there was a hook that allowed control of the sitemap, I would no longer need to do 2 as a separate post processing step

API design

The proposal would be a similar design to the createFeedItems API that we landed in: #8378

The createFeedItems API allows users to provide the following in the blog section of their docusaurus.config.js:

type CreateFeedItemsFn = (params: {
  blogPosts: BlogPost[];
  siteConfig: DocusaurusConfig;
  outDir: string;
  defaultCreateFeedItemsFn: CreateFeedItemsFn;
}) => Promise<BlogFeedItem[]>;

Usage looks like this:

/** @type {import('@docusaurus/types').Config} */
const config = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          feedOptions: {
            type: 'all',
            copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
            createFeedItems: async (params) => {
              const { blogPosts, defaultCreateFeedItems, ...rest } = params;
              return defaultCreateFeedItems({
                // keep only the 10 most recent blog posts in the feed
                blogPosts: blogPosts.filter((item, index) => index < 10),
                ...rest,
              });
            },
          },
        },
      },
    ],
  ],
};

Imagine a createSitemapItems property that could be provided as an additional property to the sitemap configuration.

createSitemapItems would be a function, which receives a single parameter. That parameter is an object with a number of properties. The most important of these would be sitemapItems. This would be a list of sitemap items. Users can then filter / mutate this list and return a new list which will be subsequently turned into the sitemap.xml.

I'd imagine this probably being implemented around about here:

docusaurus/packages/docusaurus-plugin-sitemap/src/createSitemap.ts

Line 99 in da2c0b4

const items = await createSitemapItems(params);

What do you think?

Have you tried building it?

Yes. See #10083

Self-service

• I'd be willing to contribute this feature to Docusaurus myself.