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 inhtml_theme_options, we include the variable nameininlinecode.Click on section titles to learn more about them and some basic layout configurations.For complete reference of the existing option please seethe last section of this page.

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

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

Templates and components#

There are a few major theme sections that you can customize to add/removebuilt-in components or add your own components. Each section is configured with alist ofHTML templates — these are snippets of HTML that are inserted intothe section by Sphinx.

You can choose which templates show up in each section, as well as the order inwhich they appear. This page describes the major areas that you can customize.

Header / Navigation Bar#

Located insections/header.html.

The header is at the top of the page above all other content and contains site-level information.

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

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

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

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

Article Header#

Located insections/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.

Primary sidebar (left)#

Located insections/sidebar-primary.html.

The primary sidebar is just to the left of a page’s main content.It is primarily used for between-section navigation.By default, it will show links to any siblings/children of the current active top-level section (corresponding to links in your header navigation bar).

Configuring it is a bit different from configuring the other sections because configuring the sidebar is natively supported in Sphinx, via thehtml_sidebars configuration variable.

For the primary sidebar only, you can configure templates so that they only showup on certain pages. You do so via a configuration like so inconf.py:

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

Any pages that match<page_pattern> will have their respective templatesinserted. You can also* to doglob-style matching, and may use**to match all pages.

By default, it has the following configuration:

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

• sidebar-nav-bs.html - a bootstrap-friendly navigation section.

  When there are no pages to show, it will disappear and potentially add extra space for your page’s content.

• sidebar-ethical-ads.html - a placement for ReadTheDocs’s Ethical Ads (will only show up on ReadTheDocs).

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

html_sidebars={"pagename":[]}

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

html_sidebars={"**":[]}

Footer Content#

Located insections/footer-content.html.

The footer content is a narrow bar spanning the article’s content and the secondary sidebar.It does not contain anything immediately viewable to the reader but is kept as a placeholder in case theme developers wish to re-use it in the future.

Secondary Sidebar (right)#

Located insections/sidebar-secondary.html.

The in-page sidebar is just to the right of a page’s article content and isconfigured inconf.py withhtml_theme_options['secondary_sidebar_items'].

By default, it has the following templates:

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

To learn how to further customize or remove the secondary sidebar, please checkPage Table of Contents.

Article Footer#

Located insections/footer-article.html.

The article footer exists just below your page’s article. By default, It does not contain anything immediately viewable to the reader, but is kept as a placeholder for custom or built-in templates.

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

html_theme_options={"show_prev_next":False}

Content Footer#

Located insections/footer-content.html.

The content footer exists below your page’s article and secondary sidebar.By default it is empty, but you can add templates to it with the following configuration:

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

Footer#

Located insections/footer.html.

The footer is just below a page’s main content, and is configured inconf.pywithhtml_theme_options['footer_start'],html_theme_options['footer_center'] andhtml_theme_options['footer_end'].

By default,footer_center is empty, andfooter_start andfooter_end have the following templates:

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

Within each subsection, components will stackvertically.If you’d like them to stackhorizontally use a custom CSS rule like the following:

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

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 (andwill be named accordingly).

• 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, youcould do so with the following steps:

1. Create an HTML file in a folder called_templates. For example, ifyou wanted to display the version of your documentation using a Jinjatemplate, you could create a file:_templates/version.html and put thefollowing in it:

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

2. 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’shtml_last_updated_fmt variable is set. If you want the build date displayed, the theme includes alast-updated template that you can add to one of the page regions in yourconf.py. For example:

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

If you do specifyhtml_last_updated_fmt but don’t include thelast-updated template, the theme will still write the build date into ameta 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:

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

The tag’scontent attribute will follow the format specified in thehtml_last_updated_fmt configuration variable.

References#

Please find here the full list of keys you can use in thehtml_theme_options inconf.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.csspygments_style=tangosidebars=sidebar-nav-bs.html[options]# General configurationsidebar_includehidden=Trueuse_edit_page_button=Falseexternal_links=bitbucket_url=github_url=gitlab_url=twitter_url=icon_links_label=IconLinksicon_links=analytics=show_prev_next=Truesearch_bar_text=Searchthedocs...navigation_with_keys=Falsecollapse_navigation=Falsenavigation_depth=4show_nav_level=1show_toc_level=1navbar_align=contentheader_links_before_dropdown=5header_dropdown_text=Moreswitcher=check_switcher=Truepygments_light_style=a11y-high-contrast-lightpygments_dark_style=a11y-high-contrast-darklogo=logo_link=surface_warnings=Trueback_to_top_button=True# Template placement in theme layoutsnavbar_start=navbar-logonavbar_center=navbar-navnavbar_end=theme-switcher,navbar-icon-linksnavbar_persistent=search-button-fieldarticle_header_start=breadcrumbsarticle_header_end=article_footer_items=content_footer_items=primary_sidebar_end=sidebar-ethical-adsfooter_start=copyright,sphinx-versionfooter_center=footer_end=theme-versionsecondary_sidebar_items=page-toc,edit-this-page,sourcelinkshow_version_warning_banner=Falseannouncement=# DEPRECATED (remove after 1.0 release)pygment_light_style=pygment_dark_style=