@azerion/bunosaurus-plugin-sitemap 0.0.0-stage → 4.0.0

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# `@docusaurus/plugin-sitemap`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Simple sitemap generation plugin for Docusaurus.
+
+## Usage
+
+See [plugin-sitemap documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-sitemap).

package/lib/createSitemap.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 { CreateSitemapItemsParams } from './types';
+import type { RouteBuildMetadata } from '@docusaurus/types';
+import type { PluginOptions } from './options';
+type CreateSitemapParams = CreateSitemapItemsParams & {
+    routesBuildMetadata: {
+        [location: string]: RouteBuildMetadata;
+    };
+    options: PluginOptions;
+};
+export default function createSitemap(params: CreateSitemapParams): Promise<string | null>;
+export {};

package/lib/createSitemap.js

@@ -0,0 +1,62 @@
+"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.default = createSitemap;
+const utils_1 = require("@docusaurus/utils");
+const glob_1 = require("@docusaurus/glob");
+const xml_1 = require("./xml");
+const createSitemapItem_1 = require("./createSitemapItem");
+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
+// - routes with no index metadata
+function getSitemapRoutes({ routes, routesBuildMetadata, options, }) {
+    const { ignorePatterns } = options;
+    const ignoreMatcher = (0, glob_1.createMatcher)(ignorePatterns);
+    function isRouteExcluded(route) {
+        return (ignoreMatcher(route.path) ||
+            (0, head_1.isNoIndexMetaRoute)({ routesBuildMetadata, route: route.path }));
+    }
+    return (0, utils_1.flattenRoutes)(routes).filter((route) => !isRouteExcluded(route));
+}
+// Our default implementation receives some additional parameters on purpose
+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 { routesBuildMetadata, options, routes, siteConfig } = params;
+    const defaultCreateSitemapItems = createDefaultCreateSitemapItems({ routesBuildMetadata, 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)(sitemapItems, {
+        lastmod: params.options.lastmod,
+    });
+    return xmlString;
+}

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,61 @@
+"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 = createSitemapItem;
+const utils_common_1 = require("@docusaurus/utils-common");
+const utils_1 = require("@docusaurus/utils");
+async function getRouteLastUpdatedAt(route, vcs) {
+    // Important to bail-out early here
+    // This can lead to duplicated VCS calls and performance problems
+    // See https://github.com/facebook/docusaurus/pull/11211
+    if (route.metadata?.lastUpdatedAt === null) {
+        return null;
+    }
+    if (route.metadata?.lastUpdatedAt != null) {
+        return route.metadata?.lastUpdatedAt;
+    }
+    if (route.metadata?.sourceFilePath) {
+        const lastUpdateInfo = await vcs.getFileLastUpdateInfo(route.metadata?.sourceFilePath);
+        return lastUpdateInfo?.timestamp ?? null;
+    }
+    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, vcs, }) {
+    if (lastmod === null) {
+        return null;
+    }
+    const lastUpdatedAt = (await getRouteLastUpdatedAt(route, vcs)) ?? null;
+    return lastUpdatedAt != null ? 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,
+            vcs: siteConfig.vcs,
+        }),
+    };
+}

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 { RouteBuildMetadata } from '@docusaurus/types';
+export declare function isNoIndexMetaRoute({ routesBuildMetadata, route, }: {
+    routesBuildMetadata: {
+        [location: string]: RouteBuildMetadata;
+    };
+    route: string;
+}): boolean;

package/lib/head.js

@@ -0,0 +1,18 @@
+"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 = isNoIndexMetaRoute;
+// Maybe we want to add a routeConfig.metadata.noIndex instead?
+// But using Helmet is more reliable for third-party plugins...
+function isNoIndexMetaRoute({ routesBuildMetadata, route, }) {
+    const routeBuildMetadata = routesBuildMetadata[route];
+    if (routeBuildMetadata) {
+        return routeBuildMetadata.noIndex;
+    }
+    return false;
+}

package/lib/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 { PluginOptions, Options } from './options';
+import type { LoadContext, Plugin } from '@docusaurus/types';
+export default function pluginSitemap(context: LoadContext, options: PluginOptions): Plugin<void> | null;
+export { validateOptions } from './options';
+export type { PluginOptions, Options };

package/lib/index.js

@@ -0,0 +1,51 @@
+"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.validateOptions = void 0;
+exports.default = pluginSitemap;
+const tslib_1 = require("tslib");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const fs_1 = require("@docusaurus/fs");
+const createSitemap_1 = tslib_1.__importDefault(require("./createSitemap"));
+const PluginName = 'docusaurus-plugin-sitemap';
+function pluginSitemap(context, options) {
+    if (context.siteConfig.future.experimental_router === 'hash') {
+        logger_1.default.warn(`${PluginName} does not support the Hash Router and will be disabled.`);
+        return null;
+    }
+    return {
+        name: PluginName,
+        async postBuild({ siteConfig, routes, outDir, routesBuildMetadata }) {
+            if (siteConfig.noIndex) {
+                return;
+            }
+            // Generate sitemap.
+            const generatedSitemap = await (0, createSitemap_1.default)({
+                siteConfig,
+                routes,
+                routesBuildMetadata,
+                options,
+            });
+            if (!generatedSitemap) {
+                return;
+            }
+            // Write sitemap file.
+            const sitemapPath = node_path_1.default.join(outDir, options.filename);
+            try {
+                await (0, fs_1.outputFile)(sitemapPath, generatedSitemap);
+            }
+            catch (err) {
+                logger_1.default.error('Writing sitemap failed.');
+                throw err;
+            }
+        },
+    };
+}
+var options_1 = require("./options");
+Object.defineProperty(exports, "validateOptions", { enumerable: true, get: function () { return options_1.validateOptions; } });

package/lib/options.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 { OptionValidationContext } from '@docusaurus/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.
+     * 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[];
+    /**
+     * 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
+     */
+    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;
+    /** 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

@@ -0,0 +1,59 @@
+"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.DEFAULT_OPTIONS = void 0;
+exports.validateOptions = validateOptions;
+const utils_validation_1 = require("@docusaurus/utils-validation");
+const types_1 = require("./types");
+exports.DEFAULT_OPTIONS = {
+    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(null, ...types_1.ChangeFreqList)
+        .default(exports.DEFAULT_OPTIONS.changefreq),
+    // 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),
+    createSitemapItems: utils_validation_1.Joi.function(),
+    ignorePatterns: utils_validation_1.Joi.array()
+        .items(utils_validation_1.Joi.string())
+        .default(exports.DEFAULT_OPTIONS.ignorePatterns),
+    trailingSlash: utils_validation_1.Joi.forbidden().messages({
+        'any.unknown': 'Please use the new Docusaurus global trailingSlash config instead, and the sitemaps plugin will use it.',
+    }),
+    filename: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.filename),
+});
+function validateOptions({ validate, options, }) {
+    const validatedOptions = validate(PluginOptionSchema, options);
+    return validatedOptions;
+}

package/lib/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 { 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'];
+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;
+};
+export type CreateSitemapItemsParams = {
+    siteConfig: DocusaurusConfig;
+    routes: RouteConfig[];
+};
+export type CreateSitemapItemsFn = (params: CreateSitemapItemsParams) => Promise<SitemapItem[]>;

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,28 @@
+"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 = sitemapItemsToXmlString;
+const sitemap_1 = require("sitemap");
+async function sitemapItemsToXmlString(items, options) {
+    if (items.length === 0) {
+        // Fail fast with a clearer error than the lib's EmptySitemap error
+        throw new Error("Can't generate a sitemap with no items");
+    }
+    // We could generate the XML ourselves, but we keep using the lib on purpose
+    // Users can return undocumented fields from createSitemapItems()
+    // (links, img, video, news...) that the lib serializes
+    // See https://github.com/ekalinin/sitemap.js
+    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();
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@azerion/bunosaurus-plugin-sitemap",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.0",
+  "description": "Simple sitemap generation plugin for Docusaurus.",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/azerion/bunosaurus.git",
+    "directory": "packages/docusaurus-plugin-sitemap"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@docusaurus/core": "npm:@azerion/bunosaurus-core@4.0.0",
+    "@docusaurus/fs": "npm:@azerion/bunosaurus-fs@4.0.0",
+    "@docusaurus/glob": "npm:@azerion/bunosaurus-glob@4.0.0",
+    "@docusaurus/logger": "npm:@azerion/bunosaurus-logger@4.0.0",
+    "@docusaurus/types": "npm:@azerion/bunosaurus-types@4.0.0",
+    "@docusaurus/utils": "npm:@azerion/bunosaurus-utils@4.0.0",
+    "@docusaurus/utils-common": "npm:@azerion/bunosaurus-utils-common@4.0.0",
+    "@docusaurus/utils-validation": "npm:@azerion/bunosaurus-utils-validation@4.0.0",
+    "sitemap": "^9.0.1",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@total-typescript/shoehorn": "^0.1.2"
+  },
+  "peerDependencies": {
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "engines": {
+    "bun": ">=1.4.1"
+  }
+}

package/src/createSitemap.ts

@@ -0,0 +1,93 @@
+/**
+ * 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 {flattenRoutes} from '@docusaurus/utils';
+import {createMatcher} from '@docusaurus/glob';
+import {sitemapItemsToXmlString} from './xml';
+import {createSitemapItem} from './createSitemapItem';
+import {isNoIndexMetaRoute} from './head';
+import type {CreateSitemapItemsFn, CreateSitemapItemsParams} from './types';
+import type {RouteConfig, RouteBuildMetadata} from '@docusaurus/types';
+import type {PluginOptions} from './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,
+  routesBuildMetadata,
+  options,
+}: CreateSitemapParams) {
+  const {ignorePatterns} = options;
+
+  const ignoreMatcher = createMatcher(ignorePatterns);
+
+  function isRouteExcluded(route: RouteConfig) {
+    return (
+      ignoreMatcher(route.path) ||
+      isNoIndexMetaRoute({routesBuildMetadata, route: route.path})
+    );
+  }
+
+  return flattenRoutes(routes).filter((route) => !isRouteExcluded(route));
+}
+
+// Our default implementation receives some additional parameters on purpose
+function createDefaultCreateSitemapItems(
+  internalParams: Pick<CreateSitemapParams, 'routesBuildMetadata' | '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 & {
+  routesBuildMetadata: {[location: string]: RouteBuildMetadata};
+  options: PluginOptions;
+};
+
+export default async function createSitemap(
+  params: CreateSitemapParams,
+): Promise<string | null> {
+  const {routesBuildMetadata, options, routes, siteConfig} = params;
+
+  const defaultCreateSitemapItems: CreateSitemapItemsFn =
+    createDefaultCreateSitemapItems({routesBuildMetadata, 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(sitemapItems, {
+    lastmod: params.options.lastmod,
+  });
+  return xmlString;
+}

package/src/createSitemapItem.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 {normalizeUrl} from '@docusaurus/utils';
+import type {LastModOption, SitemapItem} from './types';
+import type {DocusaurusConfig, RouteConfig, VcsConfig} from '@docusaurus/types';
+import type {PluginOptions} from './options';
+
+async function getRouteLastUpdatedAt(
+  route: RouteConfig,
+  vcs: Pick<VcsConfig, 'getFileLastUpdateInfo'>,
+): Promise<number | null | undefined> {
+  // Important to bail-out early here
+  // This can lead to duplicated VCS calls and performance problems
+  // See https://github.com/facebook/docusaurus/pull/11211
+  if (route.metadata?.lastUpdatedAt === null) {
+    return null;
+  }
+  if (route.metadata?.lastUpdatedAt != null) {
+    return route.metadata?.lastUpdatedAt;
+  }
+  if (route.metadata?.sourceFilePath) {
+    const lastUpdateInfo = await vcs.getFileLastUpdateInfo(
+      route.metadata?.sourceFilePath,
+    );
+    return lastUpdateInfo?.timestamp ?? null;
+  }
+
+  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,
+  vcs,
+}: {
+  route: RouteConfig;
+  lastmod: LastModOption | null;
+  vcs: Pick<VcsConfig, 'getFileLastUpdateInfo'>;
+}): Promise<string | null> {
+  if (lastmod === null) {
+    return null;
+  }
+  const lastUpdatedAt = (await getRouteLastUpdatedAt(route, vcs)) ?? null;
+  return lastUpdatedAt != null ? 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,
+      vcs: siteConfig.vcs,
+    }),
+  };
+}

package/src/head.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 {RouteBuildMetadata} from '@docusaurus/types';
+
+// Maybe we want to add a routeConfig.metadata.noIndex instead?
+// But using Helmet is more reliable for third-party plugins...
+export function isNoIndexMetaRoute({
+  routesBuildMetadata,
+  route,
+}: {
+  routesBuildMetadata: {[location: string]: RouteBuildMetadata};
+  route: string;
+}): boolean {
+  const routeBuildMetadata = routesBuildMetadata[route];
+
+  if (routeBuildMetadata) {
+    return routeBuildMetadata.noIndex;
+  }
+  return false;
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 path from 'node:path';
+import logger from '@docusaurus/logger';
+import {outputFile} from '@docusaurus/fs';
+import createSitemap from './createSitemap';
+import type {PluginOptions, Options} from './options';
+import type {LoadContext, Plugin} from '@docusaurus/types';
+
+const PluginName = 'docusaurus-plugin-sitemap';
+
+export default function pluginSitemap(
+  context: LoadContext,
+  options: PluginOptions,
+): Plugin<void> | null {
+  if (context.siteConfig.future.experimental_router === 'hash') {
+    logger.warn(
+      `${PluginName} does not support the Hash Router and will be disabled.`,
+    );
+    return null;
+  }
+
+  return {
+    name: PluginName,
+
+    async postBuild({siteConfig, routes, outDir, routesBuildMetadata}) {
+      if (siteConfig.noIndex) {
+        return;
+      }
+      // Generate sitemap.
+      const generatedSitemap = await createSitemap({
+        siteConfig,
+        routes,
+        routesBuildMetadata,
+        options,
+      });
+      if (!generatedSitemap) {
+        return;
+      }
+
+      // Write sitemap file.
+      const sitemapPath = path.join(outDir, options.filename);
+      try {
+        await outputFile(sitemapPath, generatedSitemap);
+      } catch (err) {
+        logger.error('Writing sitemap failed.');
+        throw err;
+      }
+    },
+  };
+}
+
+export {validateOptions} from './options';
+export type {PluginOptions, Options};

package/src/options.ts

@@ -0,0 +1,126 @@
+/**
+ * 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 {Joi} from '@docusaurus/utils-validation';
+import {ChangeFreqList, LastModOptionList} from './types';
+import type {OptionValidationContext} from '@docusaurus/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.
+   * 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[];
+
+  /**
+   * 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
+   */
+  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;
+
+  /** 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 = {
+  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>({
+  // @ts-expect-error: forbidden
+  cacheTime: 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: Joi.string()
+    .valid(null, ...ChangeFreqList)
+    .default(DEFAULT_OPTIONS.changefreq),
+
+  // 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),
+
+  createSitemapItems: Joi.function(),
+
+  ignorePatterns: Joi.array()
+    .items(Joi.string())
+    .default(DEFAULT_OPTIONS.ignorePatterns),
+  trailingSlash: Joi.forbidden().messages({
+    'any.unknown':
+      'Please use the new Docusaurus global trailingSlash config instead, and the sitemaps plugin will use it.',
+  }),
+  filename: Joi.string().default(DEFAULT_OPTIONS.filename),
+});
+
+export function validateOptions({
+  validate,
+  options,
+}: OptionValidationContext<Options, PluginOptions>): PluginOptions {
+  const validatedOptions = validate(PluginOptionSchema, options);
+  return validatedOptions;
+}

package/src/types.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 {DocusaurusConfig, RouteConfig} from '@docusaurus/types';
+
+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;
+};
+
+export type CreateSitemapItemsParams = {
+  siteConfig: DocusaurusConfig;
+  routes: RouteConfig[];
+};
+
+export type CreateSitemapItemsFn = (
+  params: CreateSitemapItemsParams,
+) => Promise<SitemapItem[]>;

package/src/xml.ts

@@ -0,0 +1,34 @@
+/**
+ * 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) {
+    // Fail fast with a clearer error than the lib's EmptySitemap error
+    throw new Error("Can't generate a sitemap with no items");
+  }
+
+  // We could generate the XML ourselves, but we keep using the lib on purpose
+  // Users can return undocumented fields from createSitemapItems()
+  // (links, img, video, news...) that the lib serializes
+  // See https://github.com/ekalinin/sitemap.js
+  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();
+}