Branding and logo#
Customize logo and title#
By default the theme will use the value of project
on the left side of the header navbar.
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, put an image in a folder that is in html_static_path, and use the following configuration:
html_static_path = ["_static"]
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, put the 2 image files in a folder that is in html_static_path
and configure the relative path to each image with logo["image_light"]
and logo["image_dark"]
in html_theme_options
, like so:
html_static_path = ["_static"]
html_theme_options = {
"logo": {
"image_light": "logo-light.png",
"image_dark": "logo-dark.png",
}
}
备注
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",
}
}
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 will appear just after your logo image if it is set.
html_theme_options = {
"logo": {
"text": "My awesome documentation",
}
}
备注
The html_title
field will work as well if no logo images are specified.
Add favicons#
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 }}">