品牌标识与徽标#

自定义徽标和标题#

默认情况下，主题将在标题导航栏的左侧使用 project 的值。这可以用徽标图像替换，并且还可以选择自定义 html_title。

适用于浅色和深色模式的单一徽标#

要使用 本地图像文件，请按照 Sphinx 文档中的说明使用 html_logo。文件必须相对于 conf.py。例如，如果您的文档在 _static/logo.png 中有徽标：

html_logo = "_static/logo.png"

要使用指向图像的 外部链接，请确保 html_logo 以 http 开头。例如：

html_logo = "https://pydata.org/wp-content/uploads/2019/06/pydata-logo-final.png"

浅色和深色模式的不同徽标#

您可以为“浅色”和“深色”模式指定不同版本的徽标图像。如果您的徽标图像不适合深色模式（背景过亮、对比度不足等），这将非常有用。

为此，请在 html_theme_options 中使用 logo["image_light"] 和 logo["image_dark"] 选项。对于每个选项，提供相对于 conf.py 的路径，如下所示：

# Assuming your `conf.py` has a sibling folder called `_static` with these files
html_theme_options = {
   "logo": {
      "image_light": "_static/logo-light.png",
      "image_dark": "_static/logo-dark.png",
   }
}

备注

image_light 和 image_dark 将覆盖 html_logo 设置。如果您仅指定了浅色或深色变体之一，未指定的变体将回退到 html_logo 的值。

自定义徽标链接#

默认情况下，徽标链接到 root_doc （通常是您的文档的第一页）。您可以改为链接到本地文档或外部网站。为此，请使用 html_theme_options["logo"]["link"] 选项并提供新链接。

例如，要引用另一个本地页面：

html_theme_options = {
    "logo": {
        "link": "some/other-page",
    }
}

要引用外部网站，请确保您的链接以 http 开头：

html_theme_options = {
    "logo": {
        "link": "https://pydata.org",
    }
}

徽标标题和替代文本#

如果您提供了徽标图像，它将替换标题导航栏中的 project 或 html_title。如果您希望在徽标旁边同时显示网站徽标和标题（或任何其他文本），您可以使用 text 属性，如下所示：

conf.py#

html_theme_options = {
    "logo": {
        "text": "My awesome documentation",
        "image_light": "_static/logo-light.png",
        "image_dark": "_static/logo-dark.png",
    }
}

但如果您只想显示徽标而不显示网站标题，那么最好提供替代文本，这有助于盲人访客和其他依赖屏幕阅读器的用户：

conf.py#

html_theme_options = {
    "logo": {
        # Because the logo is also a homepage link, including "home" in the
        # alt text is good practice
        "alt_text": "My awesome documentation - Home",
        "image_light": "_static/logo-light.png",
        "image_dark": "_static/logo-dark.png",
    }
}

在大多数情况下，您会提供 text 或 alt_text，而不是两者都提供，但在某些情况下，同时提供两者可能是有意义的：

conf.py#

html_theme_options = {
    "logo": {
        # In a left-to-right context, screen readers will read the alt text
        # first, then the text, so this example will be read as "P-G-G-P-Y
        # (short pause) Home A pretty good geometry package"
        "alt_text": "PggPy - Home",
        "text": "A pretty good geometry package",
        "image_light": "_static/logo-light.png",
        "image_dark": "_static/logo-dark.png",
    }
}

如果您不提供 text 或 alt_text，主题将提供一些默认的替代文本（否则，您的主页链接在辅助技术中可能会显示为“未标记的图像”）。默认的替代文本是 "docstitle - 主页"，但如果您提供了徽标标题（text），默认的替代文本将为空字符串（假设是，如果您提供了徽标标题，标题可能正在替代文本的工作，如上所示，您可以通过同时提供 text 和 alt_text 来覆盖此假设）。

添加网站图标#

pydata_sphinx_theme 支持标准 sphinx 网站图标配置，使用 html_favicon。在 0.15.3 版本中，对复杂和多个网站图标的支持已被弃用。相反，请使用 sphinx-favicon 扩展。它使用更灵活的参数提供相同的功能。