高级配置¶

定制 URL 方案¶

sitemap_url_scheme 默认值为 {lang}{version}{link}，其中 {lang} 和 {version} 分别由 conf.py 中的 language 和 version 配置项设置。

重要

自 Sphinx 版本 5 起，language 默认值为 "en"，如果这会导致默认方案产生不正确的 URL，请更改默认行为。

改变默认行为，将 conf.py 中的 sitemap_url_scheme 设置为所需格式。例如：

sitemap_url_scheme = "{link}"

或者对于嵌套部署，类似于：

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

备注

插件会自动将 language 和 version 值的尾部斜杠添加到方案中。你也可以从方案中省略值以获得所需的行为。

更改文件名¶

将 conf.py 中的 sitemap_filename 设置为所需的文件名，例如：

sitemap_filename = "sitemap.xml"

版本支持¶

version 指定了 sitemap 的版本。对于多版本 sitemap，为每个版本生成 sitemap 并手动将每个添加到 sitemapindex.xml 文件中。

标记版本¶

对于标记版本的部署策略，其中 latest 从分支的头部创建，版本从标记的提交创建，请检查当前提交是否与版本标记正则表达式匹配，并相应地设置 version。

# 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"

小技巧

设置主题布局中所有版本的首选 URL 为该页面的最新版本，例如：

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

语言支持¶

language 指定了主要语言。任何其他语言都会使用 locale_dirs 中内容检测到的其他语言。

例如，对于主要语言 en，以及 es 和 fr 作为检测到的翻译，sitemap 如下所示：

<?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>

使用 sitemap_locales 手动指定要包含在 sitemap 中的语言列表：

sitemap_locales = ['en', 'es']

每个语言/版本构建的最终结果类似于以下内容：

<?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>

要生成没有替代语言的主要语言，请将 sitemap_locales 设置为 [None]：

sitemap_locales = [None]

对于多语言 sitemap，为每个语言生成 sitemap 并手动将每个添加到 sitemapindex.xml 文件中。

排除页面¶

要排除一组页面，请将每个页面的路径添加到 sitemap_exclude：

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