Sphinx Sitemap Generator Extension

Warnings

• breaking Older versions of `sphinx-sitemap` (prior to 2.9.0, specifically versions before 2.8.0) experienced compatibility issues with Sphinx 7.2.x due to internal API changes within Sphinx (e.g., TocTree refactoring, `pathlib.Path` objects, and changes to JS/CSS handling). Ensure you are using `sphinx-sitemap` 2.9.0 or newer if targeting Sphinx 7.2.x or later.
  Fix: Upgrade `sphinx-sitemap` to version 2.9.0 or newer: `pip install --upgrade sphinx-sitemap`. If an upgrade is not possible, pin Sphinx to a version `< 7.2.0`.
• gotcha The `html_baseurl` configuration variable in `conf.py` is absolutely critical for `sphinx-sitemap` to generate valid, absolute URLs in your `sitemap.xml`. If this variable is not set or contains an incorrect URL, the generated sitemap will be ineffective for search engines.
  Fix: Always set `html_baseurl = 'https://your-docs-domain.com/path/'` in your `conf.py`. Ensure it accurately reflects the live URL of your documentation.
• gotcha For multi-version or multi-language Sphinx projects, `sphinx-sitemap` generates a separate sitemap for each version/language. You must then manually create a `sitemapindex.xml` file that links to these individual sitemaps to properly inform search engines of all available content.
  Fix: Refer to the `sphinx-sitemap` documentation on 'Versioning Configuration' and 'Multilingual Configuration' for detailed instructions on creating a `sitemapindex.xml`.
• gotcha When `sitemap_show_lastmod = True` is enabled, the extension attempts to add `<lastmod>` timestamps based on Git's last update time for each page. This feature requires a full Git repository history to be available. Shallow clones, which are the default behavior in many Continuous Integration (CI) environments (e.g., GitHub Actions), are not supported and will result in the omission of `<lastmod>` tags.
  Fix: In CI/CD pipelines, configure Git to perform a full clone (e.g., `fetch-depth: 0` for GitHub Actions) rather than a shallow clone if you intend to use `sitemap_show_lastmod`.
• gotcha As of Sphinx version 5, the `language` configuration value defaults to 'en'. This can affect the default URL scheme generated by `sphinx-sitemap`. If the default `{lang}{version}{link}` scheme produces incorrect URLs, particularly in multi-language setups, you may need to explicitly customize `sitemap_url_scheme`.
  Fix: Set `sitemap_url_scheme` in your `conf.py` to match your desired URL structure (e.g., `sitemap_url_scheme = "{link}"` for no language/version prefix).

Install

• pip install sphinx-sitemap Install via pip

Imports

• sphinx_sitemap

  extensions = ['sphinx_sitemap']

  Add 'sphinx_sitemap' to the `extensions` list in your `conf.py`.

Quickstart

To get started, install the library and then enable the extension by adding 'sphinx_sitemap' to the `extensions` list in your Sphinx `conf.py`. Crucially, set the `html_baseurl` configuration variable to the root URL where your documentation will be hosted for correct sitemap generation.

# In conf.py, typically located in your Sphinx project's root directory

import os

project = 'My Awesome Docs'
copyright = '2026, Your Name'

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx_sitemap',  # Add this line to enable the extension
]

# *** ESSENTIAL for sitemap generation ***
# Set the base URL of your published documentation. This is critical for sitemap validity.
html_baseurl = os.environ.get('DOCS_BASE_URL', 'https://example.com/docs/')

# Optional: Enable 'lastmod' timestamps (requires Git repository with history)
# sitemap_show_lastmod = True

# Optional: Exclude specific pages or patterns from the sitemap
# sitemap_exclude_pages = ['excluded_page.html', '**/private/*']

# To generate the sitemap, navigate to your docs directory and run:
# sphinx-build -b html . _build
# The sitemap.xml will be generated in the _build directory.