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. You can click on section titles to learn more about them and some basic layout configuration.
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
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%;
}
Templates and components#
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.
备注
When configuring templates in each section, you may omit the .html
suffix after each template if you wish.
Article Header#
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.
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).
copyright.html
edit-this-page.html
footer-article/prev-next.html
icon-links.html
last-updated.html
navbar-icon-links.html
navbar-logo.html
navbar-nav.html
page-toc.html
search-button.html
search-field.html
sidebar-ethical-ads.html
sidebar-nav-bs.html
sourcelink.html
sphinx-version.html
theme-switcher.html
version-switcher.html
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"], ... }