Skip to main content
`Ctrl`+`K`

# 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(60deg 100% 25%);
    }

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

    div.admonition.admonition-olive > .admonition-title::after {
      color: hsl(60deg 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(0deg 100% 50%); /* YouTube red */
    }

    div.admonition.admonition-youtube > .admonition-title {
      background-color: hsl(0deg 99% 18%);
      color: white;
    }

    div.admonition.admonition-youtube > .admonition-title::after {
      color: hsl(0deg 100% 50%);
      content: "\f26c"; /* fa-solid fa-tv */
    }