品牌和徽标#

自定义徽标和标题#

默认情况下，该主题将在页眉导航栏的左侧使用 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 - Home”，但是如果您提供徽标标题 (text)，则默认替代文本将为空字符串（假设如果您提供徽标标题，则标题可能正在执行替代文本的工作，如上所示，您可以通过同时提供 text 和 alt_text 来覆盖此假设）。

添加图标#

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