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.
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. You can click on section titles to learn more about them and some basic layout configuration.
.content { min-height: 14rem; justify-content: space-between; display: flex; flex-direction: column; }layout-header
Logo
Section links
Components
layout-sidebar-primary
Primary Sidebar
Links between pages in the active section.
layout-article-header
Article Header
Article Content
layout-article-footer
Article Footer
layout-sidebar-secondary
Secondary Sidebar
Within-page header links
layout-footer-content
Footer content
layout-footer
Footer
Site-wide links.
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 contentwill be centered between the other sidebar and the side of the page. - If neither sidebar is present, the
article contentwill 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 and flex-grow CSS variables with the .bd-content selector. For example, to make the content grow to fit all available width, add a custom CSS rule like:
.bd-content {
flex-grow: 1;
max-width: 100%;
}There are a few major theme sections that you can customize to add/remove 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.
The header is at the top of the page above all other content, and contains site-level information.
The header is broken up into three sections. Each section is configured in conf.py with the following configuration:
- Left section:
html_theme_options['navbar_start'] - Middle menu:
html_theme_options['navbar_center'] - Right section:
html_theme_options['navbar_end']
By default, the following configuration is used:
html_theme_options = {
...
"navbar_start": ["navbar-logo"],
"navbar_center": ["navbar-nav"],
"navbar_end": ["navbar-icon-links"]
...
}By default, the navigation bar center area will align with the content on your page. This equals the following default configuration:
html_theme_options = {
...
"navbar_align": "content"
...
}If instead you'd like these items to snap to the left (closer to the logo), use this configuration:
html_theme_options = {
...
"navbar_align": "left"
...
}If you'd like these items to snap to the right of the page, use this configuration:
html_theme_options = {
...
"navbar_align": "right"
...
}The article header is a narrow bar just above the article's content. 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.
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 sublings / 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 the html_sidebars configuration variable.
For the primary sidebar only, you can configure templates so that they only show up on certain pages. You do so via a configuration like so in conf.py:
html_sidebars = {
"<page_pattern>": ["list", "of", "templates"]
}Any pages that match <page_pattern> will have their respective templates inserted. You can also * to do glob-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).
There is a special <div> within the left sidebar that appears at the bottom of the page, regardless of the content that is above it.
To control the HTML templates that are within this div, use html_theme_options['left_sidebar_end'] in conf.py.
By default, it has the following templates:
html_theme_options = {
...
"left_sidebar_end": ["sidebar-ethical-ads"],
...
}If you'd like the left sidebar to be removed from a page, you can use the following configuration in conf.py:
html_sidebars = {
"pagename": []
}This works for glob-style patterns as well. For example:
html_sidebars = {
"folder/*": []
}If you'd like to remove the left sidebar from all pages of your documentation, use this pattern:
html_sidebars = {
"**": []
}The footer content is a narrow bar spanning the article’s content and 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.
The in-page sidebar is just to the right of a page's article content, and is configured in conf.py with html_theme_options['page_sidebar_items'].
By default, it has the following templates:
html_theme_options = {
...
"page_sidebar_items": ["page-toc", "edit-this-page", "sourcelink"],
...
}The article footer exists just below your page's article, and is primarily used for navigating between adjacent sections / pages.
By default, each page of your site will have "previous" and "next" buttons at the bottom. You can hide these buttons with the following configuration:
html_theme_options = {
"show_prev_next": False
}The footer is just below a page’s main content, and is configured in conf.py with html_theme_options['footer_items'].
By default, it has the following templates:
html_theme_options = {
...
"footer_items": ["copyright", "sphinx-version"],
...
}Each footer element is wrapped in a <div> with a footer-item class, allowing you to style the structure of these items with custom CSS.
For example, by default the footer items are displayed as blocks that stack vertically. To change this behavior so that they stack horizontally, add a rule like the following in your custom .css file.
/* Make each footer item in-line so they stack horizontally instead of vertically */
.footer-item {
display: inline-block;
}
/* Add a separating border line for all but the last item */
.footer-item:not(:last-child) {
border-right: 1px solid var(--pst-color-text-base);
margin-right: .5em;
padding-right: .5em;
}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).
copyright.htmledit-this-page.htmlfooter-article/prev-next.htmlicon-links.htmllast-updated.htmlnavbar-icon-links.htmlnavbar-logo.htmlnavbar-nav.htmlpage-toc.htmlsearch-button.htmlsearch-field.htmlsidebar-ethical-ads.htmlsidebar-nav-bs.htmlsourcelink.htmlsphinx-version.htmltheme-switcher.htmlversion-switcher.html
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.htmland 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"], ... }