Theme Structure and Layout#
This section describes some basic ways to control the layout and structure of your documentation. This theme inherits its structure and section terminology from the Sphinx Basic NG theme.
Overview of theme layout#
Below is a brief overview of the major layout of this theme.
Take a look at the diagram to understand what the major sections are called.
Where you can insert component templates in html_theme_options
, we include the variable name in inline code
.
Click on section titles to learn more about them and some basic layout configurations.
For complete reference of the existing option please see the last section of this page.
Logo
navbar_start
Section links
navbar_center
Persistent components
navbar_persistent
Components
navbar_end
article_header_start
article_header_end
Article Content
article_footer_items
prev_next_area
Horizontal spacing#
By default, the theme’s three columns have fixed widths.
The primary sidebar
will snap to the left, the secondary sidebar
will snap to the right, and the article content
will be centered in between.
If one of the sidebars is not present, then the
article content
will be centered between the other sidebar and the side of the page.If neither sidebar is present, the
article content
will be in the middle of the page.
If you’d like the article content
to take up more width than its default, use the max-width
CSS property with the following selectors:
.bd-main .bd-content .bd-article-container {
max-width: 100%; /* default is 60em */
}
The above rule will set the article content max width to the same width as the top navigation bar. To truly use all of the available page width, you also need to set the following CSS rule:
.bd-page-width {
max-width: 100%; /* default is 88rem */
}
This will affect both the article content and the top navigation bar.
Note
If you use both of the custom CSS rules above, be sure to keep them as separate rules in your CSS file. If you combine them, the result will be a CSS selector that is less specific than the two default rules in the theme, and your custom CSS will fail to override the theme defaults.
Templates and components#
There are a few major theme sections that you can customize to add/remove built-in components or add your own components. Each section is configured with a list of HTML templates — these are snippets of HTML that are inserted into the section by Sphinx.
You can choose which templates show up in each section, as well as the order in which they appear. This page describes the major areas that you can customize.
Note
When configuring templates in each section, you may omit the .html
suffix after each template if you wish.
Article Header#
Located in sections/header-article.html
.
The article header is a narrow bar just above the article’s content. There are two sub-sections that can have component templates added to them:
article_header_start
is aligned to the beginning (left) of the article header. By default, this section has thebreadcrumbs.html
component which displays links to parent pages of the current page.article_header_end
is aligned to the end (right) of the article header. By default, this section is empty.
Built-in components to insert into sections#
Below is a list of built-in templates that you can insert into any section. Note that some of them may have CSS rules that assume a specific section (and will be named accordingly).
Note
When adding/changing/overwritting a component, the “.html” suffix is optional. That’s why all of them are displayed without it in the following list.
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.
Add your own HTML templates to theme sections#
If you’d like to add your own custom template to any of these sections, you could do so with the following steps:
Create an HTML file in a folder called
_templates
. For example, if you wanted to display the version of your documentation using a Jinja template, you could create a file:_templates/version.html
and put the following in it:<!-- This will display the version of the docs --> {{ version }}
Now add the file to your menu items for one of the sections above. For example:
html_theme_options = { # ... "navbar_start": ["navbar-logo", "version"], # ... }
Build date#
By default this theme does not display the build date even when Sphinx’s html_last_updated_fmt variable is set. If you want the build date displayed, the theme includes a last-updated
template that you can add to one of the page regions in your conf.py
. For example:
html_theme_options = {
"content_footer_items": ["last-updated"],
# other settings...
}
If you do specify html_last_updated_fmt
but don’t include the last-updated
template, the theme will still write the build date into a meta
tag in the HTML header, which can be inspected by viewing the page source or extracted with an HTML parser. The tag will look like:
<meta name="docbuild:last-update" content="Aug 15, 2023">
The tag’s content
attribute will follow the format specified in the html_last_updated_fmt
configuration variable.
References#
Please find here the full list of keys you can use in the html_theme_options
in conf.py
:
[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
sidebarwidth = 270
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 =