Skip to main content
Ctrl+K

PyData Theme

  • 用户指南
  • 贡献者指南
  • 示例
  • 变更日志
    • API
    • PyData Website
    • NumFocus
    • Donate to NumFocus
  • X
  • GitHub
  • PyPI
  • PyData
  • 用户指南
  • 贡献者指南
  • 示例
  • 变更日志
  • API
  • PyData Website
  • NumFocus
  • Donate to NumFocus
  • X
  • GitHub
  • PyPI
  • PyData

Section Navigation

快速入门

  • 安装
  • 主题结构与布局

导航与链接

  • 导航深度和折叠侧边栏
  • 页面目录
  • 页眉链接
  • 源代码按钮
  • Sphinx 索引

用户接口

  • 公告横幅
  • 版本切换器下拉菜单
  • 搜索栏 / 搜索按钮
  • 键盘快捷键
  • 国际化
  • 返回顶部按钮

内容与功能

  • 主题特定元素
  • 使用 ABlog 的博客
  • Sphinx Design 组件
  • 扩展主题

主题与样式

  • 品牌标识与徽标
  • 主题变量和 CSS
  • 字体和 FontAwesome
  • 浅色和深色主题

杂项

  • 可访问性
  • 分析与使用服务
  • 添加自定义 CSS 和 JS 资源
  • 构建性能和大小
  • 主题更改、弃用和警告
  • Read the Docs 功能
  • 用户指南
  • 页眉链接

页眉链接#

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

导航栏外部链接#

您可以向导航栏添加外部链接。这些链接将显示在网站主要链接的右侧,并带有小图标,表示它们指向外部站点。您可以像这样向导航栏添加外部链接:

html_theme_options = {
  "external_links": [
      {"name": "link-one-name", "url": "https://<link-one>"},
      {"name": "link-two-name", "url": "https://<link-two>"}
  ]
}

导航栏下拉链接#

默认情况下,此主题将在标题中显示前 五个 导航链接(包括顶级链接和外部链接)。它将剩余的标题链接放入名为“更多”的 下拉菜单 中。这可以防止标题链接占用过多空间,以至于挤占 UI 组件或溢出屏幕。

要控制在放入下拉菜单之前显示的标题链接数量,请使用 header_links_before_dropdown 主题配置变量。例如,将显示的标题链接数量更改为 4 而不是 5:

html_theme_options = {
  "header_links_before_dropdown": 4
}

图标链接#

图标链接是一组图片和图标的集合,每个图标都链接到页面或外部网站。如果你想展示社交媒体图标、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 类型的图标。这是相当简单的过程:

  1. 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
      ],
    }
    
  2. 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

  3. 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.

  4. 在 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"
            }
        },
    ],
    ...
}

警告

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

上一页

页面目录

下一页

源代码按钮

On this page
  • 导航栏外部链接
  • 导航栏下拉链接
  • 图标链接
    • FontAwesome 图标
    • 图片图标
      • 位图图像图标
      • SVG 图像图标
    • 图标链接快捷方式
    • 为图标链接添加自定义属性
在 GitHub 上编辑
显示源代码

© Copyright 2019, PyData Community.

由 Sphinx 8.1.3创建。

Built with the PyData Sphinx Theme 0.16.2dev0.