页眉链接#

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

图标链接#

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

svg.fa-square-twitter {
   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 类型的图标。这是相当简单的过程：

Copy custom-icons.js into an appropriate directory of your documentation source (typically source/js). In that file you will find a list of custom icon definitions. Each definition looks like this:

{
  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 ...", // svg path
  ],
}

Remove the existing list of icon definitions and add your own using the same pattern as above:
1. Keep the value of prefix as "fa-custom"
2. Set the value of iconName to a short, sensible, lowercase name for your icon
3. Change the view box height and width to match that of your icon
4. For each custom icon you define in the list, increment the Unicode codepoint by 1: "e001", "e002", "e003"...
5. Replace the SVG path string with the path that defines your custom icon
In conf.py, add the relative path from your source directory to the custom javascript file:
```
html_js_files = [
   ...
   ("js/custom-icons.js", {"defer": "defer"}),
   ...
]
```
在 v0.17.0 版本发生变更: defer attribute is required.

重要

Do not add more than one custom-icons.js file in your conf.py.

Each custom icon js file includes a call to FontAwesome.library.add(). Your site's JavaScript can only call that function once. In our testing, subsequent calls to that function do not load additional icons.

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

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

That's it, your icon will now be inserted with the <svg> tag and not <img>! You can reference your custom FontAwesome icon in CSS using the pattern .fa-<iconName> , for example .fa-pypi.

图标链接快捷方式#

为了简化常用服务的配置，支持一些快捷方式。这些快捷方式可能会在未来的版本中被移除，转而支持 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"
            }
        },
    ],
    ...
}

警告

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