Skip to main content
Ctrl+K
PyData Theme PyData Theme

PyData Theme

Site Navigation

  • User Guide
  • Community Guide
  • Examples
  • Changelog
  • PyData
  • NumFocus
  • Donate to NumFocus
  • PyData

Site Navigation

  • User Guide
  • Community Guide
  • Examples
  • Changelog
  • PyData
  • NumFocus
  • Donate to NumFocus
  • PyData

Section Navigation

Get started

  • Installation
  • Theme Structure and Layout

Navigation and links

  • Navigation depth and collapsing sidebars
  • Page Table of Contents
  • Header links
  • Source Buttons
  • Sphinx indices

User Interface

  • Announcement banners
  • Version switcher dropdowns
  • Search bar / search button
  • Keyboard shortcuts

Content and features

  • Theme-specific elements
  • Blogs with ABlog
  • Sphinx Design Components

Theming and Style

  • Branding and logo
  • Theme variables and CSS
  • Fonts and FontAwesome
  • Light and dark themes

Miscellaneous

  • Accessibility
  • Analytics and usage services
  • Build performance and size
  • Read the Docs functionality

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 = "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",
   }
}

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 to use with your logo to replace the default (“logo image”). This can make the logo more accessible to those using screen readers or other assistive tech. To do so, use html_teme_options["logo"]["alt_text"] as in the following example:

conf.py#
html_theme_options = {
    "logo": {
        "alt_text": "foo",
    }
}

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",
    }
}

Note

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 }}">

previous

Sphinx Design Components

next

Theme variables and CSS

On this page
  • Customize logo and title
    • Single logo for light and dark mode
    • Different logos for light and dark mode
    • Customize logo link
    • Customize logo alternative text
    • Add a logo title
  • Add favicons
Edit this page
Show Source

© Copyright 2019, PyData Community.

Built with the PyData Sphinx Theme 0.12.0.

Created using Sphinx 5.3.0.