@docusaurus/plugin-sitemap 3.1.0 → 3.2.0

package/lib/createSitemap.d.ts

@@ -4,9 +4,16 @@
  * 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 } from '@docusaurus/types';
+import type { DocusaurusConfig, RouteConfig } from '@docusaurus/types';
 import type { HelmetServerState } from 'react-helmet-async';
 import type { PluginOptions } from './options';
-export default function createSitemap(siteConfig: DocusaurusConfig, routesPaths: string[], head: {
-    [location: string]: HelmetServerState;
-}, options: PluginOptions): Promise<string | null>;
+type CreateSitemapParams = {
+    siteConfig: DocusaurusConfig;
+    routes: RouteConfig[];
+    head: {
+        [location: string]: HelmetServerState;
+    };
+    options: PluginOptions;
+};
+export default function createSitemap(params: CreateSitemapParams): Promise<string | null>;
+export {};

package/lib/createSitemap.js

@@ -6,9 +6,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-const sitemap_1 = require("sitemap");
-const utils_common_1 = require("@docusaurus/utils-common");
 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) {
@@ -24,33 +26,37 @@ function isNoIndexMetaRoute({ head, route, }) {
     const meta = head[route]?.meta.toComponent();
     return meta?.some((tag) => isNoIndexMetaTag({ name: tag.props.name, content: tag.props.content }));
 }
-async function createSitemap(siteConfig, routesPaths, head, options) {
-    const { url: hostname } = siteConfig;
-    if (!hostname) {
-        throw new Error('URL in docusaurus.config.js cannot be empty/undefined.');
-    }
-    const { changefreq, priority, ignorePatterns } = options;
+// Not all routes should appear in the sitemap, and we should filter:
+// - parent routes, used for layouts
+// - routes matching options.ignorePatterns
+// - routes with no index metadata
+function getSitemapRoutes({ routes, head, options }) {
+    const { ignorePatterns } = options;
     const ignoreMatcher = (0, utils_1.createMatcher)(ignorePatterns);
     function isRouteExcluded(route) {
-        return (route.endsWith('404.html') ||
-            ignoreMatcher(route) ||
-            isNoIndexMetaRoute({ head, route }));
+        return (ignoreMatcher(route.path) || 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 [];
     }
-    const includedRoutes = routesPaths.filter((route) => !isRouteExcluded(route));
-    if (includedRoutes.length === 0) {
+    return Promise.all(sitemapRoutes.map((route) => (0, createSitemapItem_1.createSitemapItem)({
+        route,
+        siteConfig: params.siteConfig,
+        options: params.options,
+    })));
+}
+async function createSitemap(params) {
+    const items = await createSitemapItems(params);
+    if (items.length === 0) {
         return null;
     }
-    const sitemapStream = new sitemap_1.SitemapStream({ hostname });
-    includedRoutes.forEach((routePath) => sitemapStream.write({
-        url: (0, utils_common_1.applyTrailingSlash)(routePath, {
-            trailingSlash: siteConfig.trailingSlash,
-            baseUrl: siteConfig.baseUrl,
-        }),
-        changefreq,
-        priority,
-    }));
-    sitemapStream.end();
-    const generatedSitemap = (await (0, sitemap_1.streamToPromise)(sitemapStream)).toString();
-    return generatedSitemap;
+    const xmlString = await (0, xml_1.sitemapItemsToXmlString)(items, {
+        lastmod: params.options.lastmod,
+    });
+    return xmlString;
 }
 exports.default = createSitemap;

package/lib/createSitemapItem.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 { SitemapItem } from './types';
+import type { DocusaurusConfig, RouteConfig } from '@docusaurus/types';
+import type { PluginOptions } from './options';
+export declare function createSitemapItem({ route, siteConfig, options, }: {
+    route: RouteConfig;
+    siteConfig: DocusaurusConfig;
+    options: PluginOptions;
+}): Promise<SitemapItem>;

package/lib/createSitemapItem.js

@@ -0,0 +1,52 @@
+"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.createSitemapItem = void 0;
+const utils_common_1 = require("@docusaurus/utils-common");
+const utils_1 = require("@docusaurus/utils");
+async function getRouteLastUpdatedAt(route) {
+    if (route.metadata?.lastUpdatedAt) {
+        return route.metadata?.lastUpdatedAt;
+    }
+    if (route.metadata?.sourceFilePath) {
+        const lastUpdate = await (0, utils_1.getLastUpdate)(route.metadata?.sourceFilePath);
+        return lastUpdate?.lastUpdatedAt;
+    }
+    return undefined;
+}
+const LastmodFormatters = {
+    date: (timestamp) => new Date(timestamp).toISOString().split('T')[0],
+    datetime: (timestamp) => new Date(timestamp).toISOString(),
+};
+function formatLastmod(timestamp, lastmodOption) {
+    const format = LastmodFormatters[lastmodOption];
+    return format(timestamp);
+}
+async function getRouteLastmod({ route, lastmod, }) {
+    if (lastmod === null) {
+        return null;
+    }
+    const lastUpdatedAt = (await getRouteLastUpdatedAt(route)) ?? null;
+    return lastUpdatedAt ? formatLastmod(lastUpdatedAt, lastmod) : null;
+}
+async function createSitemapItem({ route, siteConfig, options, }) {
+    const { changefreq, priority, lastmod } = options;
+    return {
+        url: (0, utils_1.normalizeUrl)([
+            siteConfig.url,
+            (0, utils_common_1.applyTrailingSlash)(route.path, {
+                trailingSlash: siteConfig.trailingSlash,
+                baseUrl: siteConfig.baseUrl,
+            }),
+        ]),
+        changefreq,
+        priority,
+        lastmod: await getRouteLastmod({ route, lastmod }),
+    };
+}
+exports.createSitemapItem = createSitemapItem;

package/lib/index.js

@@ -15,12 +15,17 @@ const createSitemap_1 = tslib_1.__importDefault(require("./createSitemap"));
 function pluginSitemap(context, options) {
     return {
         name: 'docusaurus-plugin-sitemap',
-        async postBuild({ siteConfig, routesPaths, outDir, head }) {
+        async postBuild({ siteConfig, routes, outDir, head }) {
             if (siteConfig.noIndex) {
                 return;
             }
             // Generate sitemap.
-            const generatedSitemap = await (0, createSitemap_1.default)(siteConfig, routesPaths, head, options);
+            const generatedSitemap = await (0, createSitemap_1.default)({
+                siteConfig,
+                routes,
+                head,
+                options,
+            });
             if (!generatedSitemap) {
                 return;
             }

package/lib/options.d.ts

@@ -4,23 +4,38 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { EnumChangefreq } from 'sitemap';
 import type { OptionValidationContext } from '@docusaurus/types';
+import type { ChangeFreq, LastModOption } from './types';
 export type PluginOptions = {
-    /** @see https://www.sitemaps.org/protocol.html#xmlTagDefinitions */
-    changefreq: EnumChangefreq;
-    /** @see https://www.sitemaps.org/protocol.html#xmlTagDefinitions */
-    priority: number;
+    /**
+     * The path to the created sitemap file, relative to the output directory.
+     * Useful if you have two plugin instances outputting two files.
+     */
+    filename: 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.
      */
     ignorePatterns: string[];
     /**
-     * The path to the created sitemap file, relative to the output directory.
-     * Useful if you have two plugin instances outputting two files.
+     * Defines the format of the "lastmod" sitemap item entry, between:
+     * - null: do not compute/add a "lastmod" sitemap entry
+     * - "date": add a "lastmod" sitemap entry without time (YYYY-MM-DD)
+     * - "datetime": add a "lastmod" sitemap entry with time (ISO 8601 datetime)
+     * @see https://www.sitemaps.org/protocol.html#xmlTagDefinitions
+     * @see https://www.w3.org/TR/NOTE-datetime
      */
-    filename: string;
+    lastmod: LastModOption | null;
+    /**
+     * TODO Docusaurus v4 breaking change: remove useless option
+     * @see https://www.sitemaps.org/protocol.html#xmlTagDefinitions
+     */
+    changefreq: ChangeFreq | null;
+    /**
+     * TODO Docusaurus v4 breaking change: remove useless option
+     * @see https://www.sitemaps.org/protocol.html#xmlTagDefinitions
+     */
+    priority: number | null;
 };
 export type Options = Partial<PluginOptions>;
 export declare const DEFAULT_OPTIONS: PluginOptions;

package/lib/options.js

@@ -8,22 +8,41 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateOptions = exports.DEFAULT_OPTIONS = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
-const sitemap_1 = require("sitemap");
+const types_1 = require("./types");
 exports.DEFAULT_OPTIONS = {
-    changefreq: sitemap_1.EnumChangefreq.WEEKLY,
-    priority: 0.5,
-    ignorePatterns: [],
     filename: 'sitemap.xml',
+    ignorePatterns: [],
+    // TODO Docusaurus v4 breaking change
+    //  change default to "date" if no bug or perf issue reported
+    lastmod: null,
+    // TODO Docusaurus v4 breaking change
+    //  those options are useless and should be removed
+    changefreq: 'weekly',
+    priority: 0.5,
 };
 const PluginOptionSchema = utils_validation_1.Joi.object({
     // @ts-expect-error: forbidden
     cacheTime: utils_validation_1.Joi.forbidden().messages({
         'any.unknown': 'Option `cacheTime` in sitemap config is deprecated. Please remove it.',
     }),
+    // TODO remove for Docusaurus v4 breaking changes?
+    //  This is not even used by Google crawlers
+    //  See also https://github.com/facebook/docusaurus/issues/2604
     changefreq: utils_validation_1.Joi.string()
-        .valid(...Object.values(sitemap_1.EnumChangefreq))
+        .valid(null, ...types_1.ChangeFreqList)
         .default(exports.DEFAULT_OPTIONS.changefreq),
-    priority: utils_validation_1.Joi.number().min(0).max(1).default(exports.DEFAULT_OPTIONS.priority),
+    // TODO remove for Docusaurus v4 breaking changes?
+    //  This is not even used by Google crawlers
+    //  The priority is "relative", and using the same priority for all routes
+    //  does not make sense according to the spec
+    //  See also https://github.com/facebook/docusaurus/issues/2604
+    //  See also https://www.sitemaps.org/protocol.html
+    priority: utils_validation_1.Joi.alternatives()
+        .try(utils_validation_1.Joi.valid(null), utils_validation_1.Joi.number().min(0).max(1))
+        .default(exports.DEFAULT_OPTIONS.priority),
+    lastmod: utils_validation_1.Joi.string()
+        .valid(null, ...types_1.LastModOptionList)
+        .default(exports.DEFAULT_OPTIONS.lastmod),
     ignorePatterns: utils_validation_1.Joi.array()
         .items(utils_validation_1.Joi.string())
         .default(exports.DEFAULT_OPTIONS.ignorePatterns),

package/lib/types.d.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.
+ */
+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"];
+export type ChangeFreq = (typeof ChangeFreqList)[number];
+export type SitemapItem = {
+    /**
+     * URL of the page.
+     * This URL must begin with the protocol (such as http).
+     * It should eventually end with a trailing slash.
+     * It should be less than 2,048 characters.
+     */
+    url: string;
+    /**
+     * ISO 8601 date string.
+     * See also https://www.w3.org/TR/NOTE-datetime
+     *
+     * It is recommended to use one of:
+     * - date.toISOString()
+     * - YYYY-MM-DD
+     *
+     * Note: as of 2024, Google uses this value for crawling priority.
+     * See also https://github.com/facebook/docusaurus/issues/2604
+     */
+    lastmod?: string | null;
+    /**
+     * One of the specified enum values
+     *
+     * Note: as of 2024, Google ignores this value.
+     * See also https://github.com/facebook/docusaurus/issues/2604
+     */
+    changefreq?: ChangeFreq | null;
+    /**
+     * The priority of this URL relative to other URLs on your site.
+     * Valid values range from 0.0 to 1.0.
+     * The default priority of a page is 0.5.
+     *
+     * Note: as of 2024, Google ignores this value.
+     * See also https://github.com/facebook/docusaurus/issues/2604
+     */
+    priority?: number | null;
+};

package/lib/types.js

@@ -0,0 +1,21 @@
+"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.ChangeFreqList = exports.LastModOptionList = void 0;
+exports.LastModOptionList = ['date', 'datetime'];
+// types are according to the sitemap spec:
+// see also https://www.sitemaps.org/protocol.html
+exports.ChangeFreqList = [
+    'hourly',
+    'daily',
+    'weekly',
+    'monthly',
+    'yearly',
+    'always',
+    'never',
+];

package/lib/xml.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 { LastModOption, SitemapItem } from './types';
+export declare function sitemapItemsToXmlString(items: SitemapItem[], options: {
+    lastmod: LastModOption | null;
+}): Promise<string>;

package/lib/xml.js

@@ -0,0 +1,30 @@
+"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.sitemapItemsToXmlString = void 0;
+const sitemap_1 = require("sitemap");
+async function sitemapItemsToXmlString(items, options) {
+    if (items.length === 0) {
+        // Note: technically we could, but there is a bug in the lib code
+        // and the code below would never resolve, so it's better to fail fast
+        throw new Error("Can't generate a sitemap with no items");
+    }
+    // TODO remove sitemap lib dependency?
+    //  https://github.com/ekalinin/sitemap.js
+    //  it looks like an outdated confusion super old lib
+    //  we might as well achieve the same result with a pure xml lib
+    const sitemapStream = new sitemap_1.SitemapStream({
+        // WTF is this lib reformatting the string YYYY-MM-DD to datetime...
+        lastmodDateOnly: options?.lastmod === 'date',
+    });
+    items.forEach((item) => sitemapStream.write(item));
+    sitemapStream.end();
+    const buffer = await (0, sitemap_1.streamToPromise)(sitemapStream);
+    return buffer.toString();
+}
+exports.sitemapItemsToXmlString = sitemapItemsToXmlString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-sitemap",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Simple sitemap generation plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -18,16 +18,19 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.1.0",
-    "@docusaurus/logger": "3.1.0",
-    "@docusaurus/types": "3.1.0",
-    "@docusaurus/utils": "3.1.0",
-    "@docusaurus/utils-common": "3.1.0",
-    "@docusaurus/utils-validation": "3.1.0",
+    "@docusaurus/core": "3.2.0",
+    "@docusaurus/logger": "3.2.0",
+    "@docusaurus/types": "3.2.0",
+    "@docusaurus/utils": "3.2.0",
+    "@docusaurus/utils-common": "3.2.0",
+    "@docusaurus/utils-validation": "3.2.0",
     "fs-extra": "^11.1.1",
     "sitemap": "^7.1.1",
     "tslib": "^2.6.0"
   },
+  "devDependencies": {
+    "@total-typescript/shoehorn": "^0.1.2"
+  },
   "peerDependencies": {
     "react": "^18.0.0",
     "react-dom": "^18.0.0"
@@ -35,5 +38,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "a5e675821f0e8b70b591fcebf19fd60a70d55548"
+  "gitHead": "5af143651b26b39761361acd96e9c5be7ba0cb25"
 }

package/src/createSitemap.ts

@@ -6,13 +6,23 @@
  */
 
 import type {ReactElement} from 'react';
-import {SitemapStream, streamToPromise} from 'sitemap';
-import {applyTrailingSlash} from '@docusaurus/utils-common';
-import {createMatcher} from '@docusaurus/utils';
-import type {DocusaurusConfig} from '@docusaurus/types';
+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 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,
@@ -47,50 +57,51 @@ function isNoIndexMetaRoute({
   );
 }
 
-export default async function createSitemap(
-  siteConfig: DocusaurusConfig,
-  routesPaths: string[],
-  head: {[location: string]: HelmetServerState},
-  options: PluginOptions,
-): Promise<string | null> {
-  const {url: hostname} = siteConfig;
-  if (!hostname) {
-    throw new Error('URL in docusaurus.config.js cannot be empty/undefined.');
-  }
-  const {changefreq, priority, ignorePatterns} = options;
+// Not all routes should appear in the sitemap, and we should filter:
+// - parent routes, used for layouts
+// - routes matching options.ignorePatterns
+// - routes with no index metadata
+function getSitemapRoutes({routes, head, options}: CreateSitemapParams) {
+  const {ignorePatterns} = options;
 
   const ignoreMatcher = createMatcher(ignorePatterns);
 
-  function isRouteExcluded(route: string) {
+  function isRouteExcluded(route: RouteConfig) {
     return (
-      route.endsWith('404.html') ||
-      ignoreMatcher(route) ||
-      isNoIndexMetaRoute({head, route})
+      ignoreMatcher(route.path) || isNoIndexMetaRoute({head, route: route.path})
     );
   }
 
-  const includedRoutes = routesPaths.filter((route) => !isRouteExcluded(route));
+  return flattenRoutes(routes).filter((route) => !isRouteExcluded(route));
+}
 
-  if (includedRoutes.length === 0) {
-    return null;
+async function createSitemapItems(
+  params: CreateSitemapParams,
+): Promise<SitemapItem[]> {
+  const sitemapRoutes = getSitemapRoutes(params);
+  if (sitemapRoutes.length === 0) {
+    return [];
   }
-
-  const sitemapStream = new SitemapStream({hostname});
-
-  includedRoutes.forEach((routePath) =>
-    sitemapStream.write({
-      url: applyTrailingSlash(routePath, {
-        trailingSlash: siteConfig.trailingSlash,
-        baseUrl: siteConfig.baseUrl,
+  return Promise.all(
+    sitemapRoutes.map((route) =>
+      createSitemapItem({
+        route,
+        siteConfig: params.siteConfig,
+        options: params.options,
       }),
-      changefreq,
-      priority,
-    }),
+    ),
   );
+}
 
-  sitemapStream.end();
-
-  const generatedSitemap = (await streamToPromise(sitemapStream)).toString();
-
-  return generatedSitemap;
+export default async function createSitemap(
+  params: CreateSitemapParams,
+): Promise<string | null> {
+  const items = await createSitemapItems(params);
+  if (items.length === 0) {
+    return null;
+  }
+  const xmlString = await sitemapItemsToXmlString(items, {
+    lastmod: params.options.lastmod,
+  });
+  return xmlString;
 }

package/src/createSitemapItem.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 {applyTrailingSlash} from '@docusaurus/utils-common';
+import {getLastUpdate, normalizeUrl} from '@docusaurus/utils';
+import type {LastModOption, SitemapItem} from './types';
+import type {DocusaurusConfig, RouteConfig} from '@docusaurus/types';
+import type {PluginOptions} from './options';
+
+async function getRouteLastUpdatedAt(
+  route: RouteConfig,
+): Promise<number | undefined> {
+  if (route.metadata?.lastUpdatedAt) {
+    return route.metadata?.lastUpdatedAt;
+  }
+  if (route.metadata?.sourceFilePath) {
+    const lastUpdate = await getLastUpdate(route.metadata?.sourceFilePath);
+    return lastUpdate?.lastUpdatedAt;
+  }
+
+  return undefined;
+}
+
+type LastModFormatter = (timestamp: number) => string;
+
+const LastmodFormatters: Record<LastModOption, LastModFormatter> = {
+  date: (timestamp) => new Date(timestamp).toISOString().split('T')[0]!,
+  datetime: (timestamp) => new Date(timestamp).toISOString(),
+};
+
+function formatLastmod(timestamp: number, lastmodOption: LastModOption) {
+  const format = LastmodFormatters[lastmodOption];
+  return format(timestamp);
+}
+
+async function getRouteLastmod({
+  route,
+  lastmod,
+}: {
+  route: RouteConfig;
+  lastmod: LastModOption | null;
+}): Promise<string | null> {
+  if (lastmod === null) {
+    return null;
+  }
+  const lastUpdatedAt = (await getRouteLastUpdatedAt(route)) ?? null;
+  return lastUpdatedAt ? formatLastmod(lastUpdatedAt, lastmod) : null;
+}
+
+export async function createSitemapItem({
+  route,
+  siteConfig,
+  options,
+}: {
+  route: RouteConfig;
+  siteConfig: DocusaurusConfig;
+  options: PluginOptions;
+}): Promise<SitemapItem> {
+  const {changefreq, priority, lastmod} = options;
+  return {
+    url: normalizeUrl([
+      siteConfig.url,
+      applyTrailingSlash(route.path, {
+        trailingSlash: siteConfig.trailingSlash,
+        baseUrl: siteConfig.baseUrl,
+      }),
+    ]),
+    changefreq,
+    priority,
+    lastmod: await getRouteLastmod({route, lastmod}),
+  };
+}

package/src/index.ts

@@ -19,17 +19,17 @@ export default function pluginSitemap(
   return {
     name: 'docusaurus-plugin-sitemap',
 
-    async postBuild({siteConfig, routesPaths, outDir, head}) {
+    async postBuild({siteConfig, routes, outDir, head}) {
       if (siteConfig.noIndex) {
         return;
       }
       // Generate sitemap.
-      const generatedSitemap = await createSitemap(
+      const generatedSitemap = await createSitemap({
         siteConfig,
-        routesPaths,
+        routes,
         head,
         options,
-      );
+      });
       if (!generatedSitemap) {
         return;
       }

package/src/options.ts

@@ -6,33 +6,60 @@
  */
 
 import {Joi} from '@docusaurus/utils-validation';
-import {EnumChangefreq} from 'sitemap';
+import {ChangeFreqList, LastModOptionList} from './types';
 import type {OptionValidationContext} from '@docusaurus/types';
+import type {ChangeFreq, LastModOption} from './types';
 
 export type PluginOptions = {
-  /** @see https://www.sitemaps.org/protocol.html#xmlTagDefinitions */
-  changefreq: EnumChangefreq;
-  /** @see https://www.sitemaps.org/protocol.html#xmlTagDefinitions */
-  priority: number;
+  /**
+   * The path to the created sitemap file, relative to the output directory.
+   * Useful if you have two plugin instances outputting two files.
+   */
+  filename: 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.
    */
   ignorePatterns: string[];
+
   /**
-   * The path to the created sitemap file, relative to the output directory.
-   * Useful if you have two plugin instances outputting two files.
+   * Defines the format of the "lastmod" sitemap item entry, between:
+   * - null: do not compute/add a "lastmod" sitemap entry
+   * - "date": add a "lastmod" sitemap entry without time (YYYY-MM-DD)
+   * - "datetime": add a "lastmod" sitemap entry with time (ISO 8601 datetime)
+   * @see https://www.sitemaps.org/protocol.html#xmlTagDefinitions
+   * @see https://www.w3.org/TR/NOTE-datetime
    */
-  filename: string;
+  lastmod: LastModOption | null;
+
+  /**
+   * TODO Docusaurus v4 breaking change: remove useless option
+   * @see https://www.sitemaps.org/protocol.html#xmlTagDefinitions
+   */
+  changefreq: ChangeFreq | null;
+
+  /**
+   * TODO Docusaurus v4 breaking change: remove useless option
+   * @see https://www.sitemaps.org/protocol.html#xmlTagDefinitions
+   */
+  priority: number | null;
 };
 
 export type Options = Partial<PluginOptions>;
 
 export const DEFAULT_OPTIONS: PluginOptions = {
-  changefreq: EnumChangefreq.WEEKLY,
-  priority: 0.5,
-  ignorePatterns: [],
   filename: 'sitemap.xml',
+  ignorePatterns: [],
+
+  // TODO Docusaurus v4 breaking change
+  //  change default to "date" if no bug or perf issue reported
+  lastmod: null,
+
+  // TODO Docusaurus v4 breaking change
+  //  those options are useless and should be removed
+  changefreq: 'weekly',
+  priority: 0.5,
 };
 
 const PluginOptionSchema = Joi.object<PluginOptions>({
@@ -41,10 +68,28 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
     'any.unknown':
       'Option `cacheTime` in sitemap config is deprecated. Please remove it.',
   }),
+
+  // TODO remove for Docusaurus v4 breaking changes?
+  //  This is not even used by Google crawlers
+  //  See also https://github.com/facebook/docusaurus/issues/2604
   changefreq: Joi.string()
-    .valid(...Object.values(EnumChangefreq))
+    .valid(null, ...ChangeFreqList)
     .default(DEFAULT_OPTIONS.changefreq),
-  priority: Joi.number().min(0).max(1).default(DEFAULT_OPTIONS.priority),
+
+  // TODO remove for Docusaurus v4 breaking changes?
+  //  This is not even used by Google crawlers
+  //  The priority is "relative", and using the same priority for all routes
+  //  does not make sense according to the spec
+  //  See also https://github.com/facebook/docusaurus/issues/2604
+  //  See also https://www.sitemaps.org/protocol.html
+  priority: Joi.alternatives()
+    .try(Joi.valid(null), Joi.number().min(0).max(1))
+    .default(DEFAULT_OPTIONS.priority),
+
+  lastmod: Joi.string()
+    .valid(null, ...LastModOptionList)
+    .default(DEFAULT_OPTIONS.lastmod),
+
   ignorePatterns: Joi.array()
     .items(Joi.string())
     .default(DEFAULT_OPTIONS.ignorePatterns),

package/src/types.ts

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ */
+
+export const LastModOptionList = ['date', 'datetime'] as const;
+
+export type LastModOption = (typeof LastModOptionList)[number];
+
+// types are according to the sitemap spec:
+// see also https://www.sitemaps.org/protocol.html
+
+export const ChangeFreqList = [
+  'hourly',
+  'daily',
+  'weekly',
+  'monthly',
+  'yearly',
+  'always',
+  'never',
+] as const;
+
+export type ChangeFreq = (typeof ChangeFreqList)[number];
+
+// We re-recreate our own type because the "sitemap" lib types are not good
+export type SitemapItem = {
+  /**
+   * URL of the page.
+   * This URL must begin with the protocol (such as http).
+   * It should eventually end with a trailing slash.
+   * It should be less than 2,048 characters.
+   */
+  url: string;
+
+  /**
+   * ISO 8601 date string.
+   * See also https://www.w3.org/TR/NOTE-datetime
+   *
+   * It is recommended to use one of:
+   * - date.toISOString()
+   * - YYYY-MM-DD
+   *
+   * Note: as of 2024, Google uses this value for crawling priority.
+   * See also https://github.com/facebook/docusaurus/issues/2604
+   */
+  lastmod?: string | null;
+
+  /**
+   * One of the specified enum values
+   *
+   * Note: as of 2024, Google ignores this value.
+   * See also https://github.com/facebook/docusaurus/issues/2604
+   */
+  changefreq?: ChangeFreq | null;
+
+  /**
+   * The priority of this URL relative to other URLs on your site.
+   * Valid values range from 0.0 to 1.0.
+   * The default priority of a page is 0.5.
+   *
+   * Note: as of 2024, Google ignores this value.
+   * See also https://github.com/facebook/docusaurus/issues/2604
+   */
+  priority?: number | null;
+};

package/src/xml.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 {SitemapStream, streamToPromise} from 'sitemap';
+import type {LastModOption, SitemapItem} from './types';
+
+export async function sitemapItemsToXmlString(
+  items: SitemapItem[],
+  options: {lastmod: LastModOption | null},
+): Promise<string> {
+  if (items.length === 0) {
+    // Note: technically we could, but there is a bug in the lib code
+    // and the code below would never resolve, so it's better to fail fast
+    throw new Error("Can't generate a sitemap with no items");
+  }
+
+  // TODO remove sitemap lib dependency?
+  //  https://github.com/ekalinin/sitemap.js
+  //  it looks like an outdated confusion super old lib
+  //  we might as well achieve the same result with a pure xml lib
+  const sitemapStream = new SitemapStream({
+    // WTF is this lib reformatting the string YYYY-MM-DD to datetime...
+    lastmodDateOnly: options?.lastmod === 'date',
+  });
+
+  items.forEach((item) => sitemapStream.write(item));
+  sitemapStream.end();
+
+  const buffer = await streamToPromise(sitemapStream);
+  return buffer.toString();
+}