公告横幅#

您可以添加公告横幅，以吸引读者的额外关注。它将会显示在屏幕顶部，但当读者开始滚动页面时，横幅会消失。

要添加公告横幅，请使用 html_theme_options["announcement"] 配置。有两种方式可以使用此功能。

在您的主题中提供本地 HTML 内容#

默认情况下，html_theme_options["announcement"] 的值将作为原始 HTML 直接插入到您的公告横幅中。

例如，以下配置添加了简单的公告。

conf.py#

html_theme_options = {
   ...
   "announcement": "Here's a <a href='https://pydata.org'>PyData Announcement!</a>",
}

使用 JavaScript 插入远程 HTML#

您可以指定任意 URL，该 URL 将用作公告的 HTML 源。当页面加载时，JavaScript 将尝试获取此 HTML 并将其原样插入到公告横幅中。这使您可以定义 HTML 公告，并将其拉取到多个文档站点或版本中。

如果 html_theme_options["announcement"] 的值以 http 开头，它将被视为远程 HTML 的 URL。

例如，以下配置指示主题从此文档的 GitHub 仓库加载 custom-template.html 示例：

conf.py#

html_theme_options = {
   ...
   "announcement": "https://github.com/pydata/pydata-sphinx-theme/raw/main/docs/_templates/custom-template.html",
}

更新或移除公告横幅#

如果您将 html_theme_options["announcement"] 设置为纯文本或 HTML，那么要更新公告横幅，您需要修改此字符串并重新构建文档页面。要移除公告横幅，请将此值设置为空字符串并重新构建文档页面。

如果您将 html_theme_options["announcement"] 设置为 URL 字符串（以 http 开头），那么您可以编辑该 URL 处的文件来更新公告横幅。在该 URL 处保存空文件将移除公告横幅。这是使用 URL 的主要优势——您可以在不重新构建和重新部署所有文档页面的情况下更改公告横幅。例如，如果您将公告指向您仓库中的某个文件的 URL，就像我们在此文档站点上所做的那样（参见上一节），那么您可以编辑、保存并仅推送对该文件的更改（空文件 = 移除公告），而无需重新构建和重新部署所有文档。

版本警告横幅#

除了通用的公告横幅外，该主题还内置了一个横幅，用于在用户查看非最新稳定版本的文档时发出警告。要使用此功能，请将以下内容添加到您的 conf.py 中：

conf.py#

html_theme_options = {
    ...
    "show_version_warning_banner": True,
}

重要

此功能依赖于版本切换器来确定最新稳定版本的版本号。它仅在以下情况下有效：如果您的版本切换器 .json 文件中只有一个条目具有 "preferred": true 属性，并且您的条目具有 compare-versions node 模块可解析的 version 属性，例如：

{
    "name": "stable",
    "version": "9.9.9",
    "url": "https://anything",
    "preferred": true
}

如果当前活动版本低于首选版本，公告将通知用户他们正在查看旧版本文档，并提供指向首选版本的链接。如果版本高于首选版本（或者版本匹配包含字符串 "dev"、"rc" 或 "pre"），公告将提示他们正在查看不稳定的开发版本。

如果您希望为旧版文档（即在 show_version_warning_banner 配置选项可用之前构建的文档）提供类似的功能，您可以通过在所有页面前添加以下 HTML 来手动添加横幅（请确保将 URL_OF_STABLE_VERSION_OF_PROJECT 替换为有效的 URL，并根据需要调整样式）：

<div style="background-color: rgb(248, 215, 218); color: rgb(114, 28, 36); text-align: center;">
  <div>
    <div>This is documentation for <strong>an old version</strong>.
      <a href="{{ URL_OF_STABLE_VERSION_OF_PROJECT }}" style="background-color: rgb(220, 53, 69); color: rgb(255, 255, 255); margin: 1rem; padding: 0.375rem 0.75rem; border-radius: 4px; display: inline-block; text-align: center;">Switch to stable version</a>
    </div>
  </div>
</div>