Configuration¶
There are a number of options for configuring your site’s look and feel.
All configuration options are passed with the html_theme_options
variable
in your conf.py
file. This is a dictionary with key: val
pairs that
you can configure in various ways. This page describes the options available to you.
Configure project logo¶
To add a logo that’s placed at the left of your nav bar, put a logo file under your doc path’s _static folder, and use the following configuration:
html_logo = "_static/logo.png"
The logo links to master_doc
(usually the first page of your documentation) by default.
If you’d like it to link to another page or use an external link instead, use the following configuration:
html_theme_options = {
"logo_link": "<other page or external link>"
}
Configure icon links¶
If you’d like icon links to show up to the right of your main navigation bar, use the following configuration:
html_theme_options = {
...
"icon_links": [
{
"name": "GitHub",
"url": "https://github.com/<your-org>/<your-repo>",
"icon": "fab fa-github-square",
},
{
"name": "GitLab",
"url": "https://gitlab.com/<your-org>/<your-repo>",
"icon": "fab fa-gitlab",
},
{
"name": "Twitter",
"url": "https://twitter.com/<your-handle>",
"icon": "fab fa-twitter-square",
},
],
...
}
The value of icon
can be any full
FontAwesome 5 Free icon.
In addition to the main icon class, e.g. fa-cat
, the “style” class must
also be provided e.g. fab for branding, or fas for solid.
Hint
To get custom colors like “Twitter blue”, use the following in your CSS,
e.g. custom.css
:
i.fa-twitter-square:before {
color: #55acee;
}
This has already been added for the brands that have shortcuts.
The below are shortcuts for commonly-used services, but may be removed in a future
release in favor of icon_links
:
html_theme_options = {
...
"github_url": "https://github.com/<your-org>/<your-repo>",
"gitlab_url": "https://gitlab.com/<your-org>/<your-repo>",
"bitbucket_url": "https://bitbucket.org/<your-org>/<your-repo>",
"twitter_url": "https://twitter.com/<your-handle>",
...
}
Additionally, the screen-reader accessible label for this menu can be configured:
html_theme_options = {
...
"icon_links_label": "Quick Links",
...
}
Adding favicons¶
pydata_sphinx_theme
supports the
standard sphinx favicon configuration,
using html_favicon
.
Additionally, pydata_sphinx_theme
allows you to add any number of
browser- or device-specific favicons of any size. To define arbitrary favicons,
use the favicons
configuration key. The href
value can be either an
absolute URL (beginning with http
) or a local path relative to your
html_static_path
:
html_theme_options = {
"favicons": [
{
"rel": "icon",
"sizes": "16x16",
"href": "https://secure.example.com/favicon/favicon-16x16.png",
},
{
"rel": "icon",
"sizes": "32x32",
"href": "favicon-32x32.png",
},
{
"rel": "apple-touch-icon",
"sizes": "180x180",
"href": "apple-touch-icon-180x180.png"
},
]
}
pydata_sphinx_theme
will add link
tags to your document’s head
section, following this pattern:
<link rel="{{ favicon.rel }}" sizes="{{ favicon.sizes }}" href="{{ favicon.href }}">
Configure the search bar position¶
To modify the position of the search bar, add the search-field.html
template to your sidebar, or to one of the navbar positions, depending
on where you want it to be placed.
For example, if you’d like the search field to be in your side-bar, add it to the sidebar templates like so:
html_sidebars = {
"**": ["search-field.html", "sidebar-nav-bs.html", "sidebar-ethical-ads.html"]
}
If instead you’d like to put the search bar in the top navbar, use the following configuration:
html_theme_options = {
"navbar_end": ["navbar-icon-links.html", "search-field.html"]
}
Note
By default the search bar is positioned in the sidebar since this is more suitable for large navigation bars.
Configure the search bar text¶
To modify the text that is in the search bar before people click on it, add the
following configuration to your conf.py
file:
html_theme_options = {
"search_bar_text": "Your text here..."
}
Google Analytics¶
If the google_analytics_id
config option is specified (like UA-XXXXXXX
),
Google Analytics’ javascript is included in the html pages.
html_theme_options = {
"google_analytics_id": "UA-XXXXXXX",
}
Changing pages with keyboard presses¶
By default, pydata-sphinx-theme
allows users to move to the previous/next
page using the left/right arrow keys on a keyboard. To disable this behavior,
use the following configuration:
html_theme_options = {
"navigation_with_keys": False
}
Show more levels of the in-page TOC by default¶
Normally only the 2nd-level headers of a page are show in the right table of contents, and deeper levels are only shown when they are part of an active section (when it is scrolled on screen).
You can show deeper levels by default by using the following configuration, indicating how many levels should be displayed:
html_theme_options = {
"show_toc_level": 2
}
All headings up to and including the level specified will now be shown regardless of what is displayed on the page.