主题结构与布局

本节介绍了一些控制文档布局和结构的基本方法。该主题继承了 Sphinx Basic NG 主题 的结构和部分术语。

主题布局概览

以下是对该主题主要布局的简要概述。请查看图表以了解主要部分的名称。在 html_theme_options 中可以插入组件模板的位置，包含了变量名称 in inline code。点击部分标题以了解更多信息以及一些基本布局配置。如需完整参考现有选项，请参阅 本页最后一节。

页眉 / 导航栏

Logo

navbar_start

章节链接

navbar_center

持久化组件

navbar_persistent

组件

navbar_end

Primary Sidebar

活动章节中页面之间的链接。

sidebars

primary_sidebar_end

Article Header

article_header_start article_header_end

文章内容

Article Footer

article_footer_items prev_next_area

Secondary Sidebar

页面内标题链接

secondary_sidebar_items

Footer content

content_footer_items

Footer

footer_start footer_center footer_end

水平间距

默认情况下，主题的三列具有固定宽度。主侧边栏 将靠左对齐，次侧边栏 将靠右对齐，而 文章内容 将居中显示在两者之间。

• 如果其中一个侧边栏不存在，那么 文章内容 将会在另一个侧边栏和页面边缘之间居中显示。

• 如果两个侧边栏都不存在，‘文章内容’将会在页面中间显示。

如果您希望 文章内容 占据比默认值更大的宽度，可以使用以下选择器并设置 max-width CSS属性：

.bd-main .bd-content .bd-article-container {
  max-width: 100%;  /* default is 60em */
}

上述规则会将文章内容的最大宽度设置为与顶部导航栏相同的宽度。若想真正利用页面的 全部 可用宽度，您还需要设置以下 CSS 规则：

.bd-page-width {
  max-width: 100%;  /* default is 88rem */
}

这将同时影响文章内容和顶部导航栏。

备注

如果您同时使用了上述两条自定义 CSS 规则，请确保在 CSS 文件中将它们保持为独立的规则。如果将它们合并，结果将生成 特异性低于 主题中两条默认规则的 CSS 选择器，导致您的自定义 CSS 无法覆盖主题的默认设置。

模板与组件

有几个主要的主题部分可供您自定义，以添加/移除内置组件或添加您自己的组件。每个部分都通过一系列 HTML模板 进行配置——这些是由Sphinx插入到该部分的HTML代码片段。

您可以选择在每个部分中显示哪些模板，以及它们的显示顺序。本页描述了您可以自定义的主要区域。

备注

在配置每个部分的模板时，如果您愿意，可以省略每个模板后的 .html 后缀。

页眉 / 导航栏

位于 sections/header.html 中。

页眉位于页面顶部，所有其他内容之上，包含网站级别的信息。

页眉部分

页眉分为三个部分。每个部分在 conf.py 中通过以下配置进行设置：

• 左侧部分： html_theme_options['navbar_start']

• 中间菜单： html_theme_options['navbar_center']

• 右侧部分： html_theme_options['navbar_end']

• 持久化右侧部分：html_theme_options['navbar_persistent']

默认情况下，使用以下配置：

html_theme_options = {
# ...
"navbar_start": ["navbar-logo"],
"navbar_center": ["navbar-nav"],
"navbar_end": ["navbar-icon-links"],
"navbar_persistent": ["search-button"]
# ...
}

警告

持久化右侧部分 位于 navbar_end 旁边，但其元素即使在小型屏幕上，当所有其他元素折叠时，仍会在页眉中保持可见。它专为 search-button 设计，无法保证其与其他组件的兼容性。

配置导航栏居中对齐

默认情况下，导航栏的中间区域将与页面内容对齐。这等同于以下默认配置：

html_theme_options = {
   # ...
   "navbar_align": "content"
   # ...
}

如果您希望这些项目靠左对齐（更靠近标志），请使用以下配置：

html_theme_options = {
   # ...
   "navbar_align": "left"
   # ...
}

如果您希望这些项目靠右对齐，请使用以下配置：

html_theme_options = {
   # ...
   "navbar_align": "right"
   # ...
}

Article Header

位于 sections/header-article.html 中。

文章页面是位于文章内容正上方的窄栏。它有两个子部分，可以向其中添加组件模板：

• article_header_start 对齐文章页眉的开头（左侧）。默认情况下，该部分包含 breadcrumbs.html 组件，用于显示当前页面的父页面链接。

• article_header_end 对齐文章页眉的末尾（右侧）。默认情况下，该部分为空。

主侧边栏（左侧）

位于 sections/sidebar-primary.html 中。

主侧边栏位于页面 main 内容的左侧，主要用于章节之间的导航。默认情况下，它会显示当前活动顶级章节的兄弟页面或子页面链接（与页眉导航栏中的链接相对应）。

它的配置与其他部分略有不同，因为侧边栏的配置在 Sphinx 中原生支持，通过 html_sidebars 配置变量实现。

仅针对主侧边栏，您可以配置模板，使其仅在某些页面上显示。您可以通过在 conf.py 中添加如下配置来实现：

html_sidebars = {
    "<page_pattern>": ["list", "of", "templates"]
}

任何匹配 <page_pattern> 的页面都会插入相应的模板。您还可以使用 * 进行 glob 风格的匹配，或者使用 ** 匹配所有页面。

默认情况下，它具有以下配置：

html_sidebars = {
    "**": ["sidebar-nav-bs", "sidebar-ethical-ads"]
}

• sidebar-nav-bs.html - 兼容 Bootstrap 的导航部分。”

  当没有页面可显示时，它会消失，并可能为页面内容腾出额外空间。

• sidebar-ethical-ads.html - ReadTheDocs 的 Ethical Ads 展示位置（仅在 ReadTheDocs 上显示）。

主侧边栏末尾部分

主侧边栏内有特殊的 <div>，它位于页面底部，无论其上方的内容如何。

要控制此 div 内的 HTML 模板，请在 conf.py 中使用 html_theme_options['primary_sidebar_end']。

默认情况下，它具有以下模板：

html_theme_options = {
  # ...
  "primary_sidebar_end": ["sidebar-ethical-ads"],
  # ...
}

从页面中移除主侧边栏

如果您希望从页面中移除主侧边栏，可以在 conf.py 中使用以下配置：

html_sidebars = {
  "pagename": []
}

也适用于glob风格的匹配模式。例如：

html_sidebars = {
  "folder/*": []
}

如果您希望从文档的 所有 页面中移除主侧边栏，请使用以下模式：

html_sidebars = {
  "**": []
}

页脚内容

位于 sections/footer-content.html。

页脚内容是横跨文章内容和次级侧边栏的窄栏。它不包含读者可直接查看的内容，但作为占位符保留，以备主题开发者未来希望重新使用它。

次侧边栏（右侧）

位于 sections/sidebar-secondary.html。

页面内侧边栏位于页面文章内容的右侧，并通过 html_theme_options['secondary_sidebar_items'] 在 conf.py 中进行配置。

默认情况下，它具有以下模板：

html_theme_options = {
  # ...
  "secondary_sidebar_items": ["page-toc", "edit-this-page", "sourcelink"],
  # ...
}

要了解如何进一步自定义或移除次级侧边栏，请查看 页面目录。

Article Footer

位于 sections/footer-article.html 。

文章页脚位于页面文章的正下方。默认情况下，它不包含读者可直接查看的内容，但作为占位符保留，用于自定义或内置模板。

html_theme_options = {
  # ...
  "article_footer_items": [],
  # ...
}

隐藏‘上一页’和‘下一页’按钮

默认情况下，您网站的每个页面底部都会显示‘上一页’和‘下一页’按钮，位于 prev_next_area 中。您可以通过以下配置隐藏这些按钮：

html_theme_options = {
  "show_prev_next": False
}

内容页脚

位于 sections/footer-content.html。

内容页脚位于页面文章和次级侧边栏的下方。默认情况下它是空的，但您可以通过以下配置向其添加模板：

html_theme_options = {
  # ...
  "content_footer_items": ["your-template.html"],
  # ...
}

Footer

位于 sections/footer.html。

页脚位于页面主要内容的下方，并通过 html_theme_options['footer_start']、html_theme_options['footer_center'] 和 html_theme_options['footer_end'] 在 conf.py 中进行配置。

默认情况下，footer_center 为空，而 footer_start 和 footer_end 具有以下模板：

html_theme_options = {
  #...
  "footer_start": ["copyright", "sphinx-version"],
  "footer_end": ["theme-version"]
  #...
}

在每个子部分中，组件将 垂直 堆叠。如果您希望它们 水平 堆叠，请使用如下自定义 CSS 规则：

.footer-items__start, .footer-items__end {
  flex-direction: row;
}

可插入章节的内置组件

以下是可以插入任何章节的内置模板列表。请注意，其中一些模板可能具有假设特定部分的 CSS 规则（并会相应地命名）。

备注

在添加/更改/覆盖组件时，".html" 后缀是可选的。这就是为什么在以下列表中所有组件都未显示后缀的原因。

• breadcrumbs: Displays (and links to) the parent section(s) of the currently viewed page.

• copyright: Displays the copyright information (which is defined in conf.py).

• edit-this-page: Displays a link to the edit interface of the page source in the specified Version Control System.

• icon-links: Displays icon-links as list items.

• indices: Displays links to the Sphinx-generated indices (genindex, modindex, py-modindex).

• last-updated: Displays the date and time that the documentation was last built.

• navbar-icon-links: Displays icon-links in the header navbar.

• navbar-logo: Displays the logo of your documentation site, in the header navbar.

• navbar-nav: Displays links to the top-level TOCtree elements, in the header navbar.

• page-toc: Displays the current page's Table of Contents.

• prev-next: Displays links to the previous and next page in the TOCtree order.

• search-button-field: Displays a search field image that opens a search overlay when clicked.

• search-button: Displays a magnifying glass icon that opens a search overlay when clicked.

• search-field: Displays an interactive search field directly on the page.

• searchbox: An empty container that holds the "Hide Search Matches" button when it's needed.

• sidebar-ethical-ads: For sites hosted on ReadTheDocs, displays "ethical ads".

• sidebar-nav-bs: Displays the TOC-subtree for pages nested under the currently active top-level TOCtree element.

• sourcelink: Displays a link to the .rst source of the current page.

• sphinx-version: Display the version of Sphinx used to build your documentation.

• theme-switcher: Displays an icon to switch between light mode, dark mode, and auto (use browser's setting).

• theme-version: Displays the version of pydata-sphinx-theme used to build the documentation.

• version-switcher: Displays a dropdown box for switching among different versions of your documentation.

将自己的 HTML 模板添加到主题章节

如果您希望将自定义模板添加到这些章节中的任何一个，可以按照以下步骤操作：

1. 在名为 _templates 的文件夹中创建 HTML 文件。例如，如果您希望使用 Jinja 模板显示文档的版本，可以创建文件： _templates/version.html，并在其中放入以下内容：

   <!-- This will display the version of the docs -->
   {{ version }}
   

2. 现在将该文件添加到上述部分之一的菜单项中。例如：

   html_theme_options = {
   # ...
   "navbar_start": ["navbar-logo", "version"],
   # ...
   }
   

构建日期

默认情况下，即使设置了 Sphinx 的 html_last_updated_fmt 变量，此主题也不会显示构建日期。如果您希望显示构建日期，主题包含 last-updated 模板，您可以将其添加到 conf.py 中的某个页面区域。例如：

conf.py

html_theme_options = {
    "content_footer_items": ["last-updated"],
    # other settings...
}

如果您确实指定了 html_last_updated_fmt 但未包含 last-updated 模板，主题仍会将构建日期写入 HTML 头部的 meta 标签中，可以通过查看页面源代码或使用 HTML 解析器提取。该标签将如下所示：

<meta name="docbuild:last-update" content="Aug 15, 2023">

标签的 content 属性将遵循 html_last_updated_fmt 配置变量中指定的格式。

引用

请在此处查看您可以在 conf.py 中的 html_theme_options 中使用的完整键列表：

[theme]
inherit = basic
# Note that we don't link the CSS file via Sphinx
# instead we manually link it in `webpack-macros.html`
stylesheet = styles/pydata-sphinx-theme.css
pygments_style = tango
sidebars = sidebar-nav-bs.html

[options]
# General configuration
sidebar_includehidden = True
use_edit_page_button = False
external_links =
bitbucket_url =
github_url =
gitlab_url =
twitter_url =
icon_links_label = Icon Links
icon_links =
analytics =
show_prev_next = True
search_bar_text = Search the docs ...
navigation_with_keys = False
collapse_navigation = False
navigation_depth = 4
show_nav_level = 1
show_toc_level = 1
navbar_align = content
header_links_before_dropdown = 5
header_dropdown_text = More
switcher =
check_switcher = True
pygments_light_style = a11y-high-contrast-light
pygments_dark_style = a11y-high-contrast-dark
logo =
logo_link =
surface_warnings = True
back_to_top_button = True

# Template placement in theme layouts
navbar_start = navbar-logo
navbar_center = navbar-nav
navbar_end = theme-switcher, navbar-icon-links
navbar_persistent = search-button-field
article_header_start = breadcrumbs
article_header_end =
article_footer_items =
content_footer_items =
primary_sidebar_end = sidebar-ethical-ads
footer_start = copyright, sphinx-version
footer_center =
footer_end = theme-version
secondary_sidebar_items = page-toc, edit-this-page, sourcelink
show_version_warning_banner = False
announcement =

# DEPRECATED (remove after 1.0 release)
pygment_light_style =
pygment_dark_style =