页眉链接#

页眉导航栏位于每个页面的顶部，包含跨文档页面的顶层导航，以及您可以添加的额外链接和组件。这些部分介绍了您可以使用页眉导航栏控制的几件事。

图标链接#

图标链接是一组图像和图标，每个图标链接到一个页面或外部网站。它们在您希望显示社交媒体图标、GitHub 徽章或项目徽标时很有用。

这些链接采用以下形式

html_theme_options = {
    ...
    "icon_links": [
        {
            # Label for this link
            "name": "GitHub",
            # URL where the link will redirect
            "url": "https://github.com/<your-org>/<your-repo>",  # required
            # Icon class (if "type": "fontawesome"), or path to local image (if "type": "local")
            "icon": "fa-brands fa-square-github",
            # The type of image to be used (see below for details)
            "type": "fontawesome",
        }
   ]
}

此外，此菜单的屏幕阅读器可访问标签可以配置

html_theme_options = {
    ...
    "icon_links_label": "Quick Links",
    ...
}

您可以使用两种类型的图标，如下所述

FontAwesome 图标#

FontAwesome 是一组常用於网站的图标。它们包括通用形状图标（例如“arrow-down”）和特定品牌的图标（例如“GitHub”）。

您可以通过在 icon 值中指定 "type": "fontawesome" 并指定 FontAwesome 类来使用 FontAwesome 图标。 icon 的值可以是任何完整的 FontAwesome 6 Free 图标。除了主图标类（例如 fa-cat）之外，还必须提供“样式”类（例如 fa-brands 用于品牌，或 fa-solid 用于实心）。

以下是一些示例

html_theme_options = {
    ...
    "icon_links": [
        {
            "name": "GitHub",
            "url": "https://github.com/<your-org>/<your-repo>",
            "icon": "fa-brands fa-square-github",
            "type": "fontawesome",
        },
        {
            "name": "GitLab",
            "url": "https://gitlab.com/<your-org>/<your-repo>",
            "icon": "fa-brands fa-square-gitlab",
            "type": "fontawesome",
        },
        {
            "name": "Twitter",
            "url": "https://twitter.com/<your-handle>",
            "icon": "fa-brands fa-square-twitter",
            # The default for `type` is `fontawesome`, so it is not required in the above examples
        },
        {
            "name": "Mastodon",
            "url": "https://<your-host>@<your-handle>",
            "icon": "fa-brands fa-mastodon",
        },
    ],
    ...
}

提示

要获得自定义颜色（例如“Twitter 蓝色”），请在您的 CSS 中使用以下代码，例如 custom.css

i.fa-twitter-square:before {
   color: #55acee;
}

这已经为具有快捷方式的品牌添加了（参见下文）。

图像图标#

如果您想显示不在 FontAwesome 图标库中的图标图像，您也可以指定一个 URL 或指向本地图像的路径，该路径将用於图标。您也可以使用 .svg 图像，就像它们是 FontAwesome 一样，只需进行一些额外的设置。

位图图像图标#

对于所有位图图像图标，例如 .png、.jpg 等，您必须将 type 指定为本地。

注意

所有具有 "type": "local" 的图标图像都使用 <img> 标签插入文档中。如果您需要 svg 类中对象的特定功能，请参见svg 图像图标

**要在网络上显示图像**，请使用 "type": "url"，并在 icon 值中提供指向图像的 URL。例如

html_theme_options = {
    ...
    "icon_links": [
        {
            "name": "Pandas",
            "url": "https://pandas.ac.cn",
            "icon": "https://raw.githubusercontent.com/pydata/pydata-sphinx-theme/main/docs/_static/pandas-square.svg",
            "type": "url",
        },
    ],
    ...
}

**要从文件路径显示本地图像**，请使用 "type": "local"，并在 icon 值中添加相对于文档根目录的图像路径。例如

html_theme_options = {
    ...
    "icon_links": [
        {
            "name": "PyData",
            "url": "https://pydata.org",
            "icon": "_static/pydata-logo-square.png",
            "type": "local",
        },
    ],
    ...
}

技巧

使用 .svg 图像，以获得在不同屏幕尺寸下行为类似的高分辨率输出。

SVG 图像图标#

为了利用 HTML 提供的 .svg 图像的完整功能集，您需要将 .svg 设置为用作 FontAwesome 类型图标。这是一个相当简单的过程

将 custom-icon.js 的内容（位于 docs 树中）复制到文档源的适当目录（通常为 source/js），并根据需要重命名该文件。以下是必须修改的行

prefix: "fa-custom",
iconName: "pypi",
icon: [
  17.313, // viewBox width
  19.807, // viewBox height
  [], // ligature
  "e001", // unicode codepoint - private use area
  "m10.383 0.2-3.239 ...", // string definined SVG path
],

更新以下文件内容
1. iconName 为我们选择的名称之一
2. 将视窗高度和宽度更改为与您的图标匹配
3. 将 SVG 路径字符串替换为定义您自定义图标的路径
将从源目录到自定义 JavaScript 文件的相对路径添加到您的 conf.py 中
```
html_js_files = [
   ...
   "js/pypi-icon.js",
   ...
]
```

在 html_theme_options 中将图标链接设置为 FontAwesome 图标

html_theme_options = [
   ...
   "icon_links": [
      {
         "name": "PyPI",
         "url": "https://www.pypi.org",
         "icon": "fa-custom fa-pypi",
         "type": "fontawesome",
      },
   ],
   ...
]

就这样，您的图标现在将使用 <svg> 标签插入，而不是 <img>！您可以在 CSS 中使用 fa-<custom-name> 来引用您的自定义 FontAwesome 图标。

图标链接快捷方式#

有一些支持的快捷方式可以最大限度地减少对常用服务的配置。这些快捷方式可能会在将来的版本中被删除，以支持 icon_links

html_theme_options = {
    ...
    "github_url": "https://github.com/<your-org>/<your-repo>",
    "gitlab_url": "https://gitlab.com/<your-org>/<your-repo>",
    "bitbucket_url": "https://bitbucket.org/<your-org>/<your-repo>",
    "twitter_url": "https://twitter.com/<your-handle>",
    ...
}

将自定义属性添加到图标链接#

您可以将自定义属性添加到图标链接的链接元素（<a>）。如果您需要添加自定义链接行为，这将非常有用。为此，请在给定图标链接条目中使用模式 "attributes": {"attribute1": "value1"}。

例如，要指定自定义的 target 和 rel 属性，以及定义您的自定义链接类

html_theme_options = {
    ...
    "icon_links": [
        {
            "name": "PyData",
            "url": "https://pydata.org",
            "icon": "_static/pydata-logo-square.png",
            "type": "local",
            # Add additional attributes to the href link.
            # The defaults of the target, rel, class, title, and href may be overwritten.
            "attributes": {
               "target" : "_blank",
               "rel" : "noopener me",
               "class": "nav-link custom-fancy-css"
            }
        },
    ],
    ...
}

警告

这可能会使您的图标链接行为异常，并且可能会覆盖默认行为，因此请确保您知道自己在做什么！