feat: add createSitemapItems hook

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

@@ -84,6 +84,37 @@ describe('createSitemap', () => {
     expect(sitemap).not.toContain('/tags');
   });
 
+  it('excludes items that createSitemapItems configures to be ignored', async () => {
+    const sitemap = await createSitemap({
+      siteConfig,
+      routes: routes([
+        '/',
+        '/search/',
+        '/tags/',
+        '/search/foo',
+        '/tags/foo/bar',
+      ]),
+      head: {},
+      options: {
+        ...options,
+        createSitemapItems: async (params) => {
+          const {defaultCreateSitemapItems, ...rest} = params;
+          const sitemapItems = await defaultCreateSitemapItems(rest);
+          const sitemapsWithoutPageAndTags = sitemapItems.filter(
+            (sitemapItem) =>
+              !sitemapItem.url.includes('/tags/') &&
+              !sitemapItem.url.endsWith('/search/'),
+          );
+          return sitemapsWithoutPageAndTags;
+        },
+      },
+    });
+
+    expect(sitemap).not.toContain('/search/</loc>');
+    expect(sitemap).toContain('/search/foo');
+    expect(sitemap).not.toContain('/tags');
+  });
+
   it('keep trailing slash unchanged', async () => {
     const sitemap = await createSitemap({
       siteConfig,

packages/docusaurus-plugin-sitemap/src/__tests__/options.test.ts

@@ -249,4 +249,44 @@ describe('validateOptions', () => {
       );
     });
   });
+
+  describe('createSitemapItems', () => {
+    it('accept createSitemapItems undefined', () => {
+      const userOptions: Options = {
+        createSitemapItems: undefined,
+      };
+      expect(testValidate(userOptions)).toEqual(defaultOptions);
+    });
+
+    it('accept createSitemapItems valid', () => {
+      const userOptions: Options = {
+        createSitemapItems: async (params) => {
+          const {defaultCreateSitemapItems, ...rest} = params;
+          const sitemapItems = await defaultCreateSitemapItems(rest);
+          const sitemapsWithoutPageAndTags = sitemapItems.filter(
+            (sitemapItem) =>
+              !sitemapItem.url.includes('/tags/') &&
+              !sitemapItem.url.includes('/page/'),
+          );
+          return sitemapsWithoutPageAndTags;
+        },
+      };
+      expect(testValidate(userOptions)).toEqual({
+        ...defaultOptions,
+        ...userOptions,
+      });
+    });
+
+    it('rejects createSitemapItems bad input type', () => {
+      const userOptions: Options = {
+        // @ts-expect-error: test
+        createSitemapItems: 'not a function',
+      };
+      expect(() =>
+        testValidate(userOptions),
+      ).toThrowErrorMatchingInlineSnapshot(
+        `""createSitemapItems" must be of type function"`,
+      );
+    });
+  });
 });

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

@@ -9,17 +9,9 @@ import type {ReactElement} from 'react';
 import {createMatcher, flattenRoutes} from '@docusaurus/utils';
 import {sitemapItemsToXmlString} from './xml';
 import {createSitemapItem} from './createSitemapItem';
-import type {SitemapItem} from './types';
+import type {SitemapItem, DefaultCreateSitemapParams} from './types';
 import type {DocusaurusConfig, RouteConfig} from '@docusaurus/types';
 import type {HelmetServerState} from 'react-helmet-async';
-import type {PluginOptions} from './options';
-
-type CreateSitemapParams = {
-  siteConfig: DocusaurusConfig;
-  routes: RouteConfig[];
-  head: {[location: string]: HelmetServerState};
-  options: PluginOptions;
-};
 
 // Maybe we want to add a routeConfig.metadata.noIndex instead?
 // But using Helmet is more reliable for third-party plugins...
@@ -61,7 +53,7 @@ function isNoIndexMetaRoute({
 // - parent routes, used for layouts
 // - routes matching options.ignorePatterns
 // - routes with no index metadata
-function getSitemapRoutes({routes, head, options}: CreateSitemapParams) {
+function getSitemapRoutes({routes, head, options}: DefaultCreateSitemapParams) {
   const {ignorePatterns} = options;
 
   const ignoreMatcher = createMatcher(ignorePatterns);
@@ -75,8 +67,8 @@ function getSitemapRoutes({routes, head, options}: CreateSitemapParams) {
   return flattenRoutes(routes).filter((route) => !isRouteExcluded(route));
 }
 
-async function createSitemapItems(
-  params: CreateSitemapParams,
+async function defaultCreateSitemapItems(
+  params: DefaultCreateSitemapParams,
 ): Promise<SitemapItem[]> {
   const sitemapRoutes = getSitemapRoutes(params);
   if (sitemapRoutes.length === 0) {
@@ -94,13 +86,36 @@ async function createSitemapItems(
 }
 
 export default async function createSitemap(
-  params: CreateSitemapParams,
+  params: DefaultCreateSitemapParams,
 ): Promise<string | null> {
-  const items = await createSitemapItems(params);
-  if (items.length === 0) {
+  const {head, options, routes, siteConfig} = params;
+
+  const sitemapItems = params.options.createSitemapItems
+    ? await params.options.createSitemapItems({
+        routes,
+        siteConfig,
+        defaultCreateSitemapItems: (userParams: {
+          routes: RouteConfig[];
+          siteConfig: DocusaurusConfig;
+        }) =>
+          defaultCreateSitemapItems({
+            head,
+            options,
+            ...userParams,
+          }),
+      })
+    : await defaultCreateSitemapItems({
+        head,
+        options,
+        routes,
+        siteConfig,
+      });
+
+  if (sitemapItems.length === 0) {
     return null;
   }
-  const xmlString = await sitemapItemsToXmlString(items, {
+
+  const xmlString = await sitemapItemsToXmlString(sitemapItems, {
     lastmod: params.options.lastmod,
   });
   return xmlString;

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

@@ -8,7 +8,12 @@
 import {Joi} from '@docusaurus/utils-validation';
 import {ChangeFreqList, LastModOptionList} from './types';
 import type {OptionValidationContext} from '@docusaurus/types';
-import type {ChangeFreq, LastModOption} from './types';
+import type {
+  ChangeFreq,
+  DefaultCreateSitemapParams,
+  LastModOption,
+  SitemapItem,
+} from './types';
 
 export type PluginOptions = {
   /**
@@ -44,6 +49,22 @@ export type PluginOptions = {
    * @see https://www.sitemaps.org/protocol.html#xmlTagDefinitions
    */
   priority: number | null;
+
+  /** Allow control over the construction of SitemapItems */
+  createSitemapItems?: CreateSitemapItemsFn;
+};
+
+type CreateSitemapItemsFn = (
+  params: CreateSitemapItemsParams,
+) => Promise<SitemapItem[]>;
+
+type CreateSitemapItemsParams = Omit<
+  DefaultCreateSitemapParams,
+  'head' | 'options'
+> & {
+  defaultCreateSitemapItems: (
+    params: Omit<DefaultCreateSitemapParams, 'head' | 'options'>,
+  ) => Promise<SitemapItem[]>;
 };
 
 export type Options = Partial<PluginOptions>;
@@ -90,6 +111,8 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
     .valid(null, ...LastModOptionList)
     .default(DEFAULT_OPTIONS.lastmod),
 
+  createSitemapItems: Joi.function(),
+
   ignorePatterns: Joi.array()
     .items(Joi.string())
     .default(DEFAULT_OPTIONS.ignorePatterns),

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

@@ -5,6 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import type {DocusaurusConfig, RouteConfig} from '@docusaurus/types';
+import type {HelmetServerState} from 'react-helmet-async';
+import type {PluginOptions} from './options';
+
 export const LastModOptionList = ['date', 'datetime'] as const;
 
 export type LastModOption = (typeof LastModOptionList)[number];
@@ -65,3 +69,10 @@ export type SitemapItem = {
    */
   priority?: number | null;
 };
+
+export type DefaultCreateSitemapParams = {
+  siteConfig: DocusaurusConfig;
+  routes: RouteConfig[];
+  head: {[location: string]: HelmetServerState};
+  options: PluginOptions;
+};

website/docs/api/plugins/plugin-sitemap.mdx

@@ -44,11 +44,23 @@ Accepted fields:
 | `priority` | `number \| null` | `0.5` | See [sitemap docs](https://www.sitemaps.org/protocol.html#xmlTagDefinitions) |
 | `ignorePatterns` | `string[]` | `[]` | A list of glob patterns; matching route paths will be filtered from the sitemap. Note that you may need to include the base URL in here. |
 | `filename` | `string` | `sitemap.xml` | The path to the created sitemap file, relative to the output directory. Useful if you have two plugin instances outputting two files. |
+| `createSitemapItems` | <code>[CreateSitemapItemsFn](#CreateSitemapItemsFn) \| undefined</code> | `undefined` | An optional function which can be used to transform and / or filter the items in the sitemap. |
 
 ```mdx-code-block
 </APITable>
 ```
 
+### Types {#types}
+
+#### `CreateSitemapItemsFn` {#CreateSitemapItemsFn}
+
+```ts
+type CreateSitemapItemsFn = (params: {
+  siteConfig: DocusaurusConfig;
+  routes: RouteConfig[];
+}) => Promise<SitemapItem[]>;
+```
+
 :::info
 
 This plugin also respects some site config:
@@ -86,6 +98,14 @@ const config = {
   priority: 0.5,
   ignorePatterns: ['/tags/**'],
   filename: 'sitemap.xml',
+  createSitemapItems: async (params) => {
+    const {defaultCreateSitemapItems, ...rest} = params;
+    const sitemapItems = await defaultCreateSitemapItems(rest);
+    const sitemapsWithoutPage = sitemapItems.filter(
+      (sitemapItem) => !sitemapItem.url.includes('/page/'),
+    );
+    return sitemapsWithoutPage;
+  },
 };
 ```
 

website/docusaurus.config.ts

@@ -490,6 +490,16 @@ export default async function createConfigAsync() {
             lastmod: 'date',
             priority: null,
             changefreq: null,
+            createSitemapItems: async (params) => {
+              const {defaultCreateSitemapItems, ...rest} = params;
+              const sitemapItems = await defaultCreateSitemapItems(rest);
+              const sitemapsWithoutPageAndTags = sitemapItems.filter(
+                (sitemapItem) =>
+                  !sitemapItem.url.includes('/tags/') &&
+                  !sitemapItem.url.includes('/page/'),
+              );
+              return sitemapsWithoutPageAndTags;
+            },
           },
         } satisfies Preset.Options,
       ],