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

sitemap_excludes = [
    "search.html",
    "genindex.html",
]