页眉链接#

页眉导航栏位于每个页面的顶部，包含文档中页面的顶级导航，以及您可以添加的额外链接和组件。这些部分涵盖了您可以通过页眉导航栏控制的几项内容。

图标链接#

图标链接是一组图片和图标的集合，每个图标都链接到页面或外部网站。如果你想展示社交媒体图标、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”）。

您可以通过指定 "type": "fontawesome" 来使用 FontAwesome 图标，并在 icon 值中指定 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 指定为 local。

备注

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

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

html_theme_options = {
    ...
    "icon_links": [
        {
            "name": "Pandas",
            "url": "https://pandas.pydata.org",
            "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 类型的图标。这是相当简单的过程：

将位于 docs 目录树中的 custom-icon.js 文件内容复制到您的文档源代码的适当目录中（通常是 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. 调整 viewbox 的高度和宽度以匹配您的图标尺寸
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-<自定义名称> 来引用您的自定义 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"
            }
        },
    ],
    ...
}

警告

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