Branding and logo#
Customize logo and title#
By default, the theme will use the value of project
on the left side of the header navigation bar.
This can be replaced by a logo image, and optionally a custom html_title
as well.
Single logo for light and dark mode#
To use a local image file, use html_logo
as specified in the Sphinx documentation.
The file must be relative to conf.py
.
For example, if your documentation had a logo in _static/logo.png
:
html_logo = "_static/logo.png"
To use an external link to an image, make sure the html_logo
begins with http
.
For example:
html_logo = "https://pydata.org/wp-content/uploads/2019/06/pydata-logo-final.png"
Different logos for light and dark mode#
You may specify a different version of your logo image for “light” and “dark” modes. This is useful if your logo image is not adapted to a dark mode (light background, not enough contrast, etc…).
To do so, use the logo["image_light"]
and logo["image_dark"]
options in html_theme_options
.
For each, provide a path relative to conf.py
like so:
# Assuming your `conf.py` has a sibling folder called `_static` with these files
html_theme_options = {
"logo": {
"image_light": "_static/logo-light.png",
"image_dark": "_static/logo-dark.png",
}
}
Note
image_light
and image_dark
will override the html_logo
setting.
If you only specify one of the light or dark variants, the un-specified variant will fall back to the value of html_logo
.
Customize logo link#
The logo links to root_doc
(usually the first page of your documentation) by default.
You can instead link to a local document or an external website.
To do so, use the html_theme_options["logo"]["link"]
option and provide a new link.
For example, to reference another local page:
html_theme_options = {
"logo": {
"link": "some/other-page",
}
}
To reference an external website, make sure your link starts with http
:
html_theme_options = {
"logo": {
"link": "https://pydata.org",
}
}
Customize logo alternative text#
You may set a custom alt text
for your logo to replace the default "logo image"
generic description.
Adding a descriptive alt text
can help make your documentation more accessible to readers using screen readers or another assistive tech.
To do so, customize the html_theme_options["logo"]["alt_text"]
configuration option as in the following example:
html_theme_options = {
"logo": {
# Because the logo is also a homepage link, including "home" in the alt text is good practice
"alt_text": "My Project Name - Home",
}
}
Add a logo title#
To add a title in the brand section of your documentation, define a value for html_theme_options.logo["text"]
.
This title will appear next to the logo image if set.
html_theme_options = {
"logo": {
"text": "My awesome documentation",
}
}
Note
The html_title
field will work as well if no logo images are specified.
Add favicons#
Deprecated since version 0.15: Support for complex and multiple favicons will be dropped in version 0.15. Instead, use the sphinx-favicon extension. It provides the same functionality using more flexible parameters.
pydata_sphinx_theme
supports the standard sphinx favicon configuration, using html_favicon
.
Additionally, you may add any number of browser- or device-specific favicons of any size.
To do so, use the html_theme_options["favicons"]
configuration key.
The only required argument is href
, which can be either an absolute URL (beginning with http
) or a local path relative to your html_static_path
.
In addition, you may specify a size with sizes
, specify a rel
value, and specify a color
.
See this blog post on SVG favicons for more information.
For example, below we define three extra favicons of different sizes and rel
types, and one with a specific color.
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",
"color": "#000000",
},
]
}
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 }}" color="{{ favicon.color }}">