公告横幅#

您可以添加一个公告横幅，以吸引读者更多关注。它将显示在屏幕顶部，但在读者开始滚动时会消失。

要添加公告横幅，请使用 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 节点模块解析的 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>