# How to Configure Sitemap Generation for Docusaurus Sites: Complete Guide

> Easily configure sitemap generation for your Docusaurus site using the built-in plugin. Ensure your content is discoverable with this complete guide.

- Repository: [Meta/docusaurus](https://github.com/facebook/docusaurus)
- Tags: how-to-guide
- Published: 2026-03-04

---

**Docusaurus automatically generates a [`sitemap.xml`](https://github.com/facebook/docusaurus/blob/main/sitemap.xml) file via the `@docusaurus/plugin-sitemap` plugin, which is bundled with `preset-classic` and executes during the `postBuild` lifecycle to index all static routes.**

The `@docusaurus/plugin-sitemap` plugin is the standard mechanism for configuring sitemap generation for Docusaurus sites. Maintained in the `facebook/docusaurus` repository, this plugin integrates seamlessly with the classic preset to produce standards-compliant XML sitemaps that improve search engine indexing without requiring manual file maintenance.

## How Docusaurus Generates Sitemaps

### Automatic Plugin Inclusion

In [`packages/docusaurus-preset-classic/src/index.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-preset-classic/src/index.ts), the preset automatically registers the sitemap plugin when the `sitemap` option is not explicitly set to `false` and the build target is production (or debug mode). This means most Docusaurus sites generate sitemaps immediately upon building, with zero configuration required.

### The postBuild Lifecycle Hook

The actual XML generation occurs in [`packages/docusaurus-plugin-sitemap/src/index.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-sitemap/src/index.ts) within the `postBuild` lifecycle hook. After the static site build completes, the plugin invokes the `createSitemap` function with the site configuration, routes, metadata, and resolved options. If `createSitemap` returns a valid string, the plugin writes the file to `<outDir>/<options.filename>` (default: [`sitemap.xml`](https://github.com/facebook/docusaurus/blob/main/sitemap.xml)).

## Configuration Options for Docusaurus Sitemaps

### Option Validation and Defaults

User-provided options are validated against a Joi schema defined in [`packages/docusaurus-plugin-sitemap/src/options.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-sitemap/src/options.ts), with fallbacks to `DEFAULT_OPTIONS`. The global `trailingSlash` setting is respected automatically and should not be configured within the plugin options.

### Available Configuration Parameters

- **filename**: The output path relative to the build directory (default: `'sitemap.xml'`).
- **ignorePatterns**: An array of glob patterns for route paths to exclude from indexing (default: `[]`).
- **lastmod**: Controls the `<lastmod>` tag format; accepts `'date'`, `'datetime'`, or `null` (default: `null`).
- **changefreq**: Sets the `<changefreq>` tag value (default: `'weekly'`, deprecated but functional).
- **priority**: Sets the `<priority>` tag value (default: `0.5`, deprecated).
- **createSitemapItems**: An optional async function for custom item transformation, receiving routes and default items.

## Practical Configuration Examples

### Default Configuration

When using `preset-classic`, the sitemap plugin is active by default with no additional configuration required:

```javascript
// docusaurus.config.js
module.exports = {
  presets: [
    [
      'classic',
      {
        // Sitemap generated automatically at /sitemap.xml
      },
    ],
  ],
};

```

### Custom Filename and Ignore Patterns

To change the output filename and exclude specific routes:

```javascript
// docusaurus.config.js
module.exports = {
  presets: [
    [
      'classic',
      {
        sitemap: {
          filename: 'custom-sitemap.xml',
          ignorePatterns: ['/private/**', '/drafts/**', '/admin/**'],
        },
      },
    ],
  ],
};

```

### Enabling Last Modified Dates

To include `<lastmod>` tags with full ISO datetime precision:

```javascript
// docusaurus.config.js
module.exports = {
  presets: [
    [
      'classic',
      {
        sitemap: {
          lastmod: 'datetime',
        },
      },
    ],
  ],
};

```

### Custom Sitemap Items Function

For advanced use cases, transform or filter items using `createSitemapItems`:

```javascript
// docusaurus.config.js
module.exports = {
  presets: [
    [
      'classic',
      {
        sitemap: {
          createSitemapItems: async ({
            routes,
            defaultCreateSitemapItems,
          }) => {
            // Generate default items from routes
            const items = await defaultCreateSitemapItems({routes});
            
            // Add a custom static page
            items.push({
              url: '/extra-page',
              changefreq: 'monthly',
              priority: 0.7,
            });
            
            // Filter out URLs containing "secret"
            return items.filter(item => !item.url.includes('secret'));
          },
        },
      },
    ],
  ],
};

```

### Disabling the Sitemap

To completely disable sitemap generation:

```javascript
// docusaurus.config.js
module.exports = {
  presets: [
    [
      'classic',
      {
        sitemap: false,
      },
    ],
  ],
};

```

## Key Source Files and Implementation Details

Understanding the internal implementation helps debug configuration issues. The sitemap generation logic resides in three primary files within the `facebook/docusaurus` repository:

- **[`packages/docusaurus-preset-classic/src/index.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-preset-classic/src/index.ts)**: Conditionally registers the sitemap plugin based on the `sitemap` option value and build environment.
- **[`packages/docusaurus-plugin-sitemap/src/index.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-sitemap/src/index.ts)**: Implements the `postBuild` lifecycle hook, orchestrating the call to `createSitemap` and handling file system writes to `<outDir>/<filename>`.
- **[`packages/docusaurus-plugin-sitemap/src/options.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-sitemap/src/options.ts)**: Defines the TypeScript interfaces, `DEFAULT_OPTIONS`, and Joi validation schema for all user-configurable parameters.

The `createSitemap` function iterates over the site's routes, applies `ignorePatterns` filtering, injects optional `lastmod`, `changefreq`, and `priority` values, and processes any custom `createSitemapItems` transformer before generating the final XML according to the Sitemaps protocol.

## Summary

- **Docusaurus sitemap generation** is handled by `@docusaurus/plugin-sitemap`, included automatically in `preset-classic`.
- The plugin executes during the `postBuild` lifecycle, writing [`sitemap.xml`](https://github.com/facebook/docusaurus/blob/main/sitemap.xml) to the build output directory by default.
- Configure the plugin via the `sitemap` object in your preset configuration or directly in the `plugins` array.
- Key options include `filename`, `ignorePatterns`, `lastmod`, and the advanced `createSitemapItems` transformer for custom logic.
- Source code in [`packages/docusaurus-plugin-sitemap/src/index.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-sitemap/src/index.ts) and [`options.ts`](https://github.com/facebook/docusaurus/blob/main/options.ts) defines the validation schema and generation logic.

## Frequently Asked Questions

### Is the sitemap plugin enabled by default in Docusaurus?

Yes. When using `@docusaurus/preset-classic`, the sitemap plugin is automatically included unless explicitly disabled. In [`packages/docusaurus-preset-classic/src/index.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-preset-classic/src/index.ts), the preset adds the plugin when the `sitemap` option is not `false` and the build target is production (or debug mode). No manual installation is required for standard setups.

### How do I exclude specific pages from the Docusaurus sitemap?

Use the `ignorePatterns` configuration option, which accepts an array of glob patterns matching route paths to exclude. For example, set `ignorePatterns: ['/private/**', '/admin/**']` in your [`docusaurus.config.js`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js) under the `sitemap` preset options. These patterns are applied during the `createSitemap` execution in [`packages/docusaurus-plugin-sitemap/src/index.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-sitemap/src/index.ts), filtering matching routes before XML generation.

### Can I customize the sitemap filename in Docusaurus?

Yes. Set the `filename` option in your sitemap configuration to change the output path relative to the build directory. The default value is `'sitemap.xml'`, but you can specify alternatives like `'custom-sitemap.xml'` or `'seo/sitemap.xml'`. This value is validated in [`packages/docusaurus-plugin-sitemap/src/options.ts`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-sitemap/src/options.ts) and used in the `postBuild` hook to determine the write location in `<outDir>/<filename>`.

### Does Docusaurus support lastmod tags in sitemaps?

Yes. Docusaurus supports the `<lastmod>` tag via the `lastmod` configuration option. Set it to `'date'` for ISO date format (YYYY-MM-DD) or `'datetime'` for full ISO datetime precision. The default is `null`, which omits the tag. This setting is processed during the `createSitemap` function execution, injecting the appropriate timestamp format into each URL entry according to the Sitemaps protocol.