页眉链接#
页眉导航栏位于每个页面的顶部,包含文档中页面的顶级导航,以及您可以添加的额外链接和组件。这些部分涵盖了您可以通过页眉导航栏控制的几项内容。
图标链接#
图标链接是一组图片和图标的集合,每个图标都链接到页面或外部网站。如果你想展示社交媒体图标、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:
Keep the value of
prefix
as "fa-custom"Set the value of
iconName
to a short, sensible, lowercase name for your iconChange the view box height and width to match that of your icon
For each custom icon you define in the list, increment the Unicode codepoint by 1:
"e001"
,"e002"
,"e003"
...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 yourconf.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"
}
},
],
...
}
警告
这可能会使您的图标链接行为异常,并可能覆盖默认行为,因此请确保您知道自己在做什么!