How to Configure Sitemap Generation for Docusaurus Sites: Complete Guide

Docusaurus automatically generates a 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, 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 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).

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, 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:

// 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:

// 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:

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

Custom Sitemap Items Function

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

// 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:

// 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: Conditionally registers the sitemap plugin based on the sitemap option value and build environment.
• 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: 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 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 and 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, 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 under the sitemap preset options. These patterns are applied during the createSitemap execution in 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}