Skip to main content
Ctrl+K
PyData Theme

PyData Theme

Site Navigation

  • User Guide
  • Contributor Guide
  • Examples
  • Changelog
    • API
    • PyData
    • NumFocus
    • Donate to NumFocus
  • Twitter
  • GitHub
  • PyPI
  • PyData

Site Navigation

  • User Guide
  • Contributor Guide
  • Examples
  • Changelog
    • API
    • PyData
    • NumFocus
    • Donate to NumFocus
  • Twitter
  • GitHub
  • PyPI
  • 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
  • Internationalization

Content and features

  • Theme-specific elements
  • Blogs with ABlog
  • Sphinx Design Components
  • Extending the theme

Theming and Style

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

Miscellaneous

  • Accessibility
  • Analytics and usage services
  • Add custom CSS and JS assets
  • Build performance and size
  • Read the Docs functionality
  • User Guide
  • Branding and logo

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:

conf.py#
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 }}">

previous

Extending the theme

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 on GitHub
Show Source

© Copyright 2019, PyData Community.

Created using Sphinx 5.3.0.

Built with the PyData Sphinx Theme 0.14.2dev0.