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",
]