@docusaurus/plugin-sitemap 3.2.1 → 3.3.1

package/lib/createSitemap.d.ts

@@ -4,12 +4,10 @@
  * This source code is licensed under the MIT license found in the
  * 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 { CreateSitemapItemsParams } from './types';
 import type { PluginOptions } from './options';
-type CreateSitemapParams = {
-    siteConfig: DocusaurusConfig;
-    routes: RouteConfig[];
+import type { HelmetServerState } from 'react-helmet-async';
+type CreateSitemapParams = CreateSitemapItemsParams & {
     head: {
         [location: string]: HelmetServerState;
     };

package/lib/createSitemap.js

@@ -9,23 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const utils_1 = require("@docusaurus/utils");
 const xml_1 = require("./xml");
 const createSitemapItem_1 = require("./createSitemapItem");
-// Maybe we want to add a routeConfig.metadata.noIndex instead?
-// But using Helmet is more reliable for third-party plugins...
-function isNoIndexMetaRoute({ head, route, }) {
-    const isNoIndexMetaTag = ({ name, content, }) => {
-        if (!name || !content) {
-            return false;
-        }
-        return (
-        // meta name is not case-sensitive
-        name.toLowerCase() === 'robots' &&
-            // Robots directives are not case-sensitive
-            content.toLowerCase().includes('noindex'));
-    };
-    // https://github.com/staylor/react-helmet-async/pull/167
-    const meta = head[route]?.meta.toComponent();
-    return meta?.some((tag) => isNoIndexMetaTag({ name: tag.props.name, content: tag.props.content }));
-}
+const head_1 = require("./head");
 // Not all routes should appear in the sitemap, and we should filter:
 // - parent routes, used for layouts
 // - routes matching options.ignorePatterns
@@ -34,27 +18,42 @@ function getSitemapRoutes({ routes, head, options }) {
     const { ignorePatterns } = options;
     const ignoreMatcher = (0, utils_1.createMatcher)(ignorePatterns);
     function isRouteExcluded(route) {
-        return (ignoreMatcher(route.path) || isNoIndexMetaRoute({ head, route: route.path }));
+        return (ignoreMatcher(route.path) || (0, head_1.isNoIndexMetaRoute)({ head, route: route.path }));
     }
     return (0, utils_1.flattenRoutes)(routes).filter((route) => !isRouteExcluded(route));
 }
-async function createSitemapItems(params) {
-    const sitemapRoutes = getSitemapRoutes(params);
-    if (sitemapRoutes.length === 0) {
-        return [];
-    }
-    return Promise.all(sitemapRoutes.map((route) => (0, createSitemapItem_1.createSitemapItem)({
-        route,
-        siteConfig: params.siteConfig,
-        options: params.options,
-    })));
+// Our default implementation receives some additional parameters on purpose
+// Params such as "head" are "messy" and not directly exposed to the user
+function createDefaultCreateSitemapItems(internalParams) {
+    return async (params) => {
+        const sitemapRoutes = getSitemapRoutes({ ...params, ...internalParams });
+        if (sitemapRoutes.length === 0) {
+            return [];
+        }
+        return Promise.all(sitemapRoutes.map((route) => (0, createSitemapItem_1.createSitemapItem)({
+            route,
+            siteConfig: params.siteConfig,
+            options: internalParams.options,
+        })));
+    };
 }
 async function createSitemap(params) {
-    const items = await createSitemapItems(params);
-    if (items.length === 0) {
+    const { head, options, routes, siteConfig } = params;
+    const defaultCreateSitemapItems = createDefaultCreateSitemapItems({ head, options });
+    const sitemapItems = params.options.createSitemapItems
+        ? await params.options.createSitemapItems({
+            routes,
+            siteConfig,
+            defaultCreateSitemapItems,
+        })
+        : await defaultCreateSitemapItems({
+            routes,
+            siteConfig,
+        });
+    if (sitemapItems.length === 0) {
         return null;
     }
-    const xmlString = await (0, xml_1.sitemapItemsToXmlString)(items, {
+    const xmlString = await (0, xml_1.sitemapItemsToXmlString)(sitemapItems, {
         lastmod: params.options.lastmod,
     });
     return xmlString;

package/lib/head.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { HelmetServerState } from 'react-helmet-async';
+export declare function isNoIndexMetaRoute({ head, route, }: {
+    head: {
+        [location: string]: HelmetServerState;
+    };
+    route: string;
+}): boolean;

package/lib/head.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNoIndexMetaRoute = void 0;
+// Maybe we want to add a routeConfig.metadata.noIndex instead?
+// But using Helmet is more reliable for third-party plugins...
+function isNoIndexMetaRoute({ head, route, }) {
+    const isNoIndexMetaTag = ({ name, content, }) => {
+        if (!name || !content) {
+            return false;
+        }
+        return (
+        // meta name is not case-sensitive
+        name.toLowerCase() === 'robots' &&
+            // Robots directives are not case-sensitive
+            content.toLowerCase().includes('noindex'));
+    };
+    // https://github.com/staylor/react-helmet-async/pull/167
+    const meta = head[route]?.meta.toComponent();
+    return (meta?.some((tag) => isNoIndexMetaTag({ name: tag.props.name, content: tag.props.content })) ?? false);
+}
+exports.isNoIndexMetaRoute = isNoIndexMetaRoute;

package/lib/options.d.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { OptionValidationContext } from '@docusaurus/types';
-import type { ChangeFreq, LastModOption } from './types';
+import type { ChangeFreq, LastModOption, SitemapItem, CreateSitemapItemsFn, CreateSitemapItemsParams } from './types';
 export type PluginOptions = {
     /**
      * The path to the created sitemap file, relative to the output directory.
@@ -36,7 +36,13 @@ export type PluginOptions = {
      * @see https://www.sitemaps.org/protocol.html#xmlTagDefinitions
      */
     priority: number | null;
+    /** Allow control over the construction of SitemapItems */
+    createSitemapItems?: CreateSitemapItemsOption;
 };
+type CreateSitemapItemsOption = (params: CreateSitemapItemsParams & {
+    defaultCreateSitemapItems: CreateSitemapItemsFn;
+}) => Promise<SitemapItem[]>;
 export type Options = Partial<PluginOptions>;
 export declare const DEFAULT_OPTIONS: PluginOptions;
 export declare function validateOptions({ validate, options, }: OptionValidationContext<Options, PluginOptions>): PluginOptions;
+export {};

package/lib/options.js

@@ -43,6 +43,7 @@ const PluginOptionSchema = utils_validation_1.Joi.object({
     lastmod: utils_validation_1.Joi.string()
         .valid(null, ...types_1.LastModOptionList)
         .default(exports.DEFAULT_OPTIONS.lastmod),
+    createSitemapItems: utils_validation_1.Joi.function(),
     ignorePatterns: utils_validation_1.Joi.array()
         .items(utils_validation_1.Joi.string())
         .default(exports.DEFAULT_OPTIONS.ignorePatterns),

package/lib/types.d.ts

@@ -4,6 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import type { DocusaurusConfig, RouteConfig } from '@docusaurus/types';
 export declare const LastModOptionList: readonly ["date", "datetime"];
 export type LastModOption = (typeof LastModOptionList)[number];
 export declare const ChangeFreqList: readonly ["hourly", "daily", "weekly", "monthly", "yearly", "always", "never"];
@@ -45,3 +46,8 @@ export type SitemapItem = {
      */
     priority?: number | null;
 };
+export type CreateSitemapItemsParams = {
+    siteConfig: DocusaurusConfig;
+    routes: RouteConfig[];
+};
+export type CreateSitemapItemsFn = (params: CreateSitemapItemsParams) => Promise<SitemapItem[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-sitemap",
-  "version": "3.2.1",
+  "version": "3.3.1",
   "description": "Simple sitemap generation plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,12 +18,12 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.2.1",
-    "@docusaurus/logger": "3.2.1",
-    "@docusaurus/types": "3.2.1",
-    "@docusaurus/utils": "3.2.1",
-    "@docusaurus/utils-common": "3.2.1",
-    "@docusaurus/utils-validation": "3.2.1",
+    "@docusaurus/core": "3.3.1",
+    "@docusaurus/logger": "3.3.0",
+    "@docusaurus/types": "3.3.0",
+    "@docusaurus/utils": "3.3.0",
+    "@docusaurus/utils-common": "3.3.0",
+    "@docusaurus/utils-validation": "3.3.0",
     "fs-extra": "^11.1.1",
     "sitemap": "^7.1.1",
     "tslib": "^2.6.0"
@@ -38,5 +38,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "f268e15264e208e6faf26117258162e988b53773"
+  "gitHead": "f3524cf332e803ff82783ee9c1c86c4342fc1f71"
 }

package/src/createSitemap.ts

@@ -5,57 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-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 {DocusaurusConfig, RouteConfig} from '@docusaurus/types';
-import type {HelmetServerState} from 'react-helmet-async';
+import {isNoIndexMetaRoute} from './head';
+import type {CreateSitemapItemsFn, CreateSitemapItemsParams} from './types';
+import type {RouteConfig} from '@docusaurus/types';
 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...
-function isNoIndexMetaRoute({
-  head,
-  route,
-}: {
-  head: {[location: string]: HelmetServerState};
-  route: string;
-}) {
-  const isNoIndexMetaTag = ({
-    name,
-    content,
-  }: {
-    name?: string;
-    content?: string;
-  }): boolean => {
-    if (!name || !content) {
-      return false;
-    }
-    return (
-      // meta name is not case-sensitive
-      name.toLowerCase() === 'robots' &&
-      // Robots directives are not case-sensitive
-      content.toLowerCase().includes('noindex')
-    );
-  };
-
-  // https://github.com/staylor/react-helmet-async/pull/167
-  const meta = head[route]?.meta.toComponent() as unknown as
-    | ReactElement<{name?: string; content?: string}>[]
-    | undefined;
-  return meta?.some((tag) =>
-    isNoIndexMetaTag({name: tag.props.name, content: tag.props.content}),
-  );
-}
+import type {HelmetServerState} from 'react-helmet-async';
 
 // Not all routes should appear in the sitemap, and we should filter:
 // - parent routes, used for layouts
@@ -75,32 +32,57 @@ function getSitemapRoutes({routes, head, options}: CreateSitemapParams) {
   return flattenRoutes(routes).filter((route) => !isRouteExcluded(route));
 }
 
-async function createSitemapItems(
-  params: CreateSitemapParams,
-): Promise<SitemapItem[]> {
-  const sitemapRoutes = getSitemapRoutes(params);
-  if (sitemapRoutes.length === 0) {
-    return [];
-  }
-  return Promise.all(
-    sitemapRoutes.map((route) =>
-      createSitemapItem({
-        route,
-        siteConfig: params.siteConfig,
-        options: params.options,
-      }),
-    ),
-  );
+// Our default implementation receives some additional parameters on purpose
+// Params such as "head" are "messy" and not directly exposed to the user
+function createDefaultCreateSitemapItems(
+  internalParams: Pick<CreateSitemapParams, 'head' | 'options'>,
+): CreateSitemapItemsFn {
+  return async (params) => {
+    const sitemapRoutes = getSitemapRoutes({...params, ...internalParams});
+    if (sitemapRoutes.length === 0) {
+      return [];
+    }
+    return Promise.all(
+      sitemapRoutes.map((route) =>
+        createSitemapItem({
+          route,
+          siteConfig: params.siteConfig,
+          options: internalParams.options,
+        }),
+      ),
+    );
+  };
 }
 
+type CreateSitemapParams = CreateSitemapItemsParams & {
+  head: {[location: string]: HelmetServerState};
+  options: PluginOptions;
+};
+
 export default async function createSitemap(
   params: CreateSitemapParams,
 ): Promise<string | null> {
-  const items = await createSitemapItems(params);
-  if (items.length === 0) {
+  const {head, options, routes, siteConfig} = params;
+
+  const defaultCreateSitemapItems: CreateSitemapItemsFn =
+    createDefaultCreateSitemapItems({head, options});
+
+  const sitemapItems = params.options.createSitemapItems
+    ? await params.options.createSitemapItems({
+        routes,
+        siteConfig,
+        defaultCreateSitemapItems,
+      })
+    : await defaultCreateSitemapItems({
+        routes,
+        siteConfig,
+      });
+
+  if (sitemapItems.length === 0) {
     return null;
   }
-  const xmlString = await sitemapItemsToXmlString(items, {
+
+  const xmlString = await sitemapItemsToXmlString(sitemapItems, {
     lastmod: params.options.lastmod,
   });
   return xmlString;

package/src/head.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {ReactElement} from 'react';
+import type {HelmetServerState} from 'react-helmet-async';
+
+// Maybe we want to add a routeConfig.metadata.noIndex instead?
+// But using Helmet is more reliable for third-party plugins...
+export function isNoIndexMetaRoute({
+  head,
+  route,
+}: {
+  head: {[location: string]: HelmetServerState};
+  route: string;
+}): boolean {
+  const isNoIndexMetaTag = ({
+    name,
+    content,
+  }: {
+    name?: string;
+    content?: string;
+  }): boolean => {
+    if (!name || !content) {
+      return false;
+    }
+    return (
+      // meta name is not case-sensitive
+      name.toLowerCase() === 'robots' &&
+      // Robots directives are not case-sensitive
+      content.toLowerCase().includes('noindex')
+    );
+  };
+
+  // https://github.com/staylor/react-helmet-async/pull/167
+  const meta = head[route]?.meta.toComponent() as unknown as
+    | ReactElement<{name?: string; content?: string}>[]
+    | undefined;
+  return (
+    meta?.some((tag) =>
+      isNoIndexMetaTag({name: tag.props.name, content: tag.props.content}),
+    ) ?? false
+  );
+}

package/src/options.ts

@@ -8,7 +8,13 @@
 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,
+  LastModOption,
+  SitemapItem,
+  CreateSitemapItemsFn,
+  CreateSitemapItemsParams,
+} from './types';
 
 export type PluginOptions = {
   /**
@@ -44,8 +50,17 @@ export type PluginOptions = {
    * @see https://www.sitemaps.org/protocol.html#xmlTagDefinitions
    */
   priority: number | null;
+
+  /** Allow control over the construction of SitemapItems */
+  createSitemapItems?: CreateSitemapItemsOption;
 };
 
+type CreateSitemapItemsOption = (
+  params: CreateSitemapItemsParams & {
+    defaultCreateSitemapItems: CreateSitemapItemsFn;
+  },
+) => Promise<SitemapItem[]>;
+
 export type Options = Partial<PluginOptions>;
 
 export const DEFAULT_OPTIONS: PluginOptions = {
@@ -90,6 +105,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),

package/src/types.ts

@@ -5,6 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import type {DocusaurusConfig, RouteConfig} from '@docusaurus/types';
+
 export const LastModOptionList = ['date', 'datetime'] as const;
 
 export type LastModOption = (typeof LastModOptionList)[number];
@@ -65,3 +67,12 @@ export type SitemapItem = {
    */
   priority?: number | null;
 };
+
+export type CreateSitemapItemsParams = {
+  siteConfig: DocusaurusConfig;
+  routes: RouteConfig[];
+};
+
+export type CreateSitemapItemsFn = (
+  params: CreateSitemapItemsParams,
+) => Promise<SitemapItem[]>;