A small sphinx extension to make it possible to add a “toggle button” to sections of your page.

You can also add a toggle button to arbitrary chunks of content. For example, click the toggle button to the right just below.


It’s a code block!

a = "wow, very python"

See Usage for more information.


sphinx-togglebutton is designed for the sphinx-book-theme. It should work properly on other themes, but if you notice any CSS bugs, please open an issue!


You can install sphinx-togglebutton with pip:

pip install sphinx-togglebutton

Then, activate it in your sphinx build by adding it to your conf.py configuration file, like so:


extensions = [

See Usage for information about how to use sphinx-togglebutton.


There are two main ways to use sphinx-togglebutton:

  • Create dropdown admonitions with the dropdown class

  • Make arbitrary chunks of content “toggle-able” with the toggle:: directive

Toggle any content with the toggle directive

To add toggle-able content, use the toggle directive. This directive will wrap its content in a toggle-able container. You can call it like so:

.. toggle::

    Here is my toggle-able content!

The code above results in:

Here is my toggle-able content!

To show the toggle-able content by default, use the :show: flag.

.. toggle::

    Here is my toggle-able content!

It results in the following:

Here is my toggle-able content!


Below are a few configuration points for sphinx-togglebutton.

Control the togglebutton hover text

You can control the “hint” text that is displayed next to togglebuttons when their content is collapsed. To do so, use the following configuration variable in your conf.py file:

togglebutton_hint = "My text"


This is a simple reference section to double-check styling etc.

Here’s how they look right after one another:


This is my note.


This is my second.

This is my first.

This is my second.