Advanced Configuration¶

Customizing the URL Scheme¶

sitemap_url_scheme defaults to {lang}{version}{link}, where {lang} and {version} get set by language and version in conf.py.

Important

As of Sphinx version 5, language defaults to "en", if that makes the default scheme produce the incorrect URL, then change the default behavior.

To change the default behavior, set the value of sitemap_url_scheme in conf.py to the desired format. For example:

sitemap_url_scheme = "{link}"

Or for nested deployments, something like:

sitemap_url_scheme = "{version}{lang}subdir/{link}"

Note

The extension automatically appends trailing slashes to both the language and version values. You can also omit values from the scheme for desired behavior.

Changing the Filename¶

Set sitemap_filename in conf.py to the desired filename, for example:

sitemap_filename = "sitemap.xml"

Version Support¶

version specifies the version of the sitemap. For multi-version sitemaps, generate a sitemap per version and then manually add each to a sitemapindex.xml file.

Tagged Releases¶

For a tagged release deploy strategy where the latest gets created from head of the branch and versions get created from tagged commits, check to see if the current commit matches the release tag regex and set version accordingly.

# check if the current commit is tagged as a release (vX.Y.Z) and set the version
GIT_TAG_OUTPUT = subprocess.check_output(["git", "tag", "--points-at", "HEAD"])
current_tag = GIT_TAG_OUTPUT.decode().strip()
if re.match(r"^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$", current_tag):
    version = current_tag
else:
    version = "latest"

Tip

Set the canonical URL in the theme layout of all versions to the latest version of that page, for example:

<link rel="canonical" href="https://my-site.com/docs/latest/index.html"/>

Language Support¶

language specifies the primary language. Any alternative languages get detected using the contents of locale_dirs.

For example, with a primary language of en, and es and fr as detected translations, the sitemap look like this:

<?xml version="1.0" encoding="utf-8"?>
<urlset xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://my-site.com/docs/en/index.html</loc>
    <xhtml:link href="https://my-site.com/docs/es/index.html" hreflang="es" rel="alternate"/>
    <xhtml:link href="https://my-site.com/docs/fr/index.html" hreflang="fr" rel="alternate"/>
    <xhtml:link href="https://my-site.com/docs/en/index.html" hreflang="en" rel="alternate"/>
  </url>
  <url>
    <loc>https://my-site.com/docs/en/about.html</loc>
    <xhtml:link href="https://my-site.com/docs/es/about.html" hreflang="es" rel="alternate"/>
    <xhtml:link href="https://my-site.com/docs/fr/about.html" hreflang="fr" rel="alternate"/>
    <xhtml:link href="https://my-site.com/docs/en/about.html" hreflang="en" rel="alternate"/>
  </url>
</urlset>

Use sitemap_locales to manually specify a list of locales to include in the sitemap:

sitemap_locales = ['en', 'es']

The end result looks something like the following for each language/version build:

<?xml version="1.0" encoding="utf-8"?>
<urlset xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://my-site.com/docs/en/index.html</loc>
    <xhtml:link href="https://my-site.com/docs/es/index.html" hreflang="es" rel="alternate"/>
    <xhtml:link href="https://my-site.com/docs/en/index.html" hreflang="en" rel="alternate"/>
  </url>
  <url>
    <loc>https://my-site.com/docs/en/about.html</loc>
    <xhtml:link href="https://my-site.com/docs/es/about.html" hreflang="es" rel="alternate"/>
    <xhtml:link href="https://my-site.com/docs/en/about.html" hreflang="en" rel="alternate"/>
  </url>
</urlset>

To generate the primary language with no alternatives, set sitemap_locales to [None]:

sitemap_locales = [None]

For multilingual sitemaps, generate a sitemap per language and then manually add each to a sitemapindex.xml file.

Excluding Pages¶

To exclude a set of pages, add each page’s path to sitemap_excludes. You can use exact paths or wildcard patterns:

sitemap_excludes = [
    "search.html",     # Exact match
    "genindex.html",   # Exact match
    "modules/*",       # Wildcard pattern - matches files starting with "_modules/"
]

Unix-style wildcards are supported:

* matches any number of characters
? matches any single character
[seq] matches any character in seq
[!seq] matches any character not in seq

Adding Last Modified Timestamps¶

To enable last modified timestamps in your sitemap, set sitemap_show_lastmod to True in conf.py:

sitemap_show_lastmod = True

When enabled, the extension uses Git to determine the last modified date for each page based on the most recent commit that modified the source file. This produces sitemap entries like:

<url>
  <loc>https://my-site.com/docs/en/index.html</loc>
  <lastmod>2024-01-15T10:30:00+00:00</lastmod>
</url>

Important

This feature requires Git to be available and your documentation to be in a Git repository. If Git is not available or the file is not tracked, no <lastmod> element will be added for that page. Shallow clones, which is the default for GitHub Actions, are not supported at this time.

Tip

The <lastmod> timestamps are particularly useful for RAG (Retrieval-Augmented Generation) systems that need to identify recently updated content for incremental updates.

Formatting XML Output¶

To add indention to the XML output, set sitemap_indent to the number of spaces for indentation in conf.py:

sitemap_indent = 2

Set to 0 (the default) to disable indentation:

sitemap_indent = 0