Extending the theme

There are many extensions available for Sphinx that can enhance your site or provide powerful customization abilities. Here we describe a few customizations that are popular with pydata-sphinx-theme users.

Collapsible admonitions

The sphinx-togglebutton extension provides optional show/hide behavior for admonitions. Follow their installation instructions, then add it to the extentions list in your conf.py:

extensions = [
    # [...]
    "sphinx_togglebutton"
]

Then add the dropdown class to any admonition directive (shown here on a note admonition):

Note

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

rst

.. note::
    :class: dropdown

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.

markdown

```{note}
:class: dropdown

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

Custom admonition styles

A limited set of admonitions are built-in to docutils (the rST → HTML engine that underlies Sphinx). However, it is possible to create custom admonitions with their own default colors, icons, and titles.

Customizing the title

Although most admonitions have a default title like note or warning, a generic admonition directive is built-in to docutils/Sphinx. In this theme, its color defaults to the same color as note admonitions, and it has a bell icon:

Custom title!

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

The title is specified on the same line as the .. admonition:: directive:

rst

.. admonition:: Custom title!

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.

markdown

```{admonition} Custom title!

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

Styling with semantic color names

You can re-style any admonition to match any of the built-in admonition types using any of the theme’s semantic color names as a class (this is most useful for custom-titled admonitions):

Custom title with “warning” style

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Note that it updates both the color and the icon. See Theme variables and CSS for a list of all semantic color names.

rst

.. admonition:: Custom title with "warning" style
    :class: warning

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.

markdown

```{admonition} Custom title with "warning" style
:class: warning

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

This theme defines classes for the standard docutils admonition types (attention, caution, etc) and additionally supports seealso and todo admonitions (see Admonitions for a demo of all built-in admonition styles).

Customizing the color

Besides the pre-defined semantic color classes (see previous section) you can also add a bespoke color to any admonition by defining your own CSS class. Example:

Admonition with custom “olive” color

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

To do this, you will need to add a class to your custom.css file, as in the example below. Be sure to use the same color for border-color and color and a different shade for background-color:

rst

.. admonition:: Admonition with custom "olive" color
    :class: admonition-olive

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.

markdown

```{admonition} Admonition with custom "olive" color
:class: admonition-olive

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

And add the following to your custom.css file:

/* <your static path>/custom.css */

div.admonition.admonition-olive {
  border-color: hsl(60, 100%, 25%);
}
div.admonition.admonition-olive > .admonition-title {
  background-color: hsl(60, 100%, 14%);
  color: white;
}
div.admonition.admonition-olive > .admonition-title:after {
  color: hsl(60, 100%, 25%);
}

Using a custom icon

Customizing the icon uses a similar process to customizing the color: create a new CSS class in your custom.css file. The theme supports fontawesome v6 icons (“free” and “brands” sets). To use an icon, copy its unicode value into your custom class as shown in the CSS tab below:

Check out my custom icon

Lorem ipsum dolor sit amet, consectetur adipiscing elit.

rst

.. admonition:: Check out my custom icon
    :class: admonition-icon

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.

markdown

```{admonition} Check out my custom icon
:class: admonition-icon

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```

And add the following css to your custom.css file:

/* <your static path>/custom.css */

div.admonition.admonition-icon > .admonition-title:after {
  content: "\f24e"; /* the fa-scale icon */
}

Combining all three customizations

Here we demonstrate an admonition with a custom icon, color, and title (and also make it collapsible). Note that the multiple admonition class names are space-separated:

YouTube

rst

.. admonition:: YouTube
    :class: dropdown admonition-youtube

    ..  youtube:: dQw4w9WgXcQ

markdown

````{admonition} YouTube
:class: dropdown admonition-youtube

```{youtube} dQw4w9WgXcQ
```

````

And add the following css to your custom.css file:

/* <your static path>/custom.css */

div.admonition.admonition-youtube {
  border-color: hsl(0, 100%, 50%); /* YouTube red */
}
div.admonition.admonition-youtube > .admonition-title {
  background-color: hsl(0, 99%, 18%);
  color: white;
}
div.admonition.admonition-youtube > .admonition-title:after {
  color: hsl(0, 100%, 50%);
  content: "\f26c"; /* fa-solid fa-tv */
}