Use and configure

This page covers how to use and configure / customize sphinx-togglebutton.

There are three main ways to use sphinx-togglebutton:

• Wrap arbitrary objects in a toggle button via a CSS selector

• Collapse admonitions with the dropdown class

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

Each is described below

Collapse a block of content with a CSS selector

You can hide any content and display a toggle button to show it by using certain CSS classes. sphinx-togglebutton will wrap elements with these classes in a <details> block like so:

<details>
  <summary>Click to show</summary>
  <!-- Element that had a CSS class selector -->
</details>

```{image} https://media.giphy.com/media/FaKV1cVKlVRxC/giphy.gif
:class: toggle
```

Configure the CSS selector used to insert toggle buttons

By default, sphinx-togglebutton will use this selector:

.toggle, .admonition.dropdown

However, you can customize this behavior with the togglebutton_selector configuration value. To specify the selector to use, pass a valid CSS selector as a string:

example

Configure sphinx-togglebutton to look for a .toggle-this-element class and an element with ID #my-special-id instead of .toggle and .admonition.dropdown.

sphinx_togglebutton_selector = ".toggle-this-element, #my-special-id"

Collapse admonitions with the dropdown class

sphinx-togglebutton treats admonitions as a special case if they are selected. If a Sphinx admonition matches the toggle button selector, then its title will be displayed with a button to reveal its content.

```{admonition} This will be shown
:class: dropdown
And this will be hidden!
```

This will be shown

And this will be hidden!

This works for any kind of Sphinx admoniton:

Note

A note!

Warning

A warning!

If you add the class toggle-shown, it will be un-toggled by default but collapsable (:class: dropdown, toggle-shown).

Use the {toggle} directive to toggle blocks of content

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:

MARKDOWN

```{toggle}
Here is my toggle-able content!
```

RST

.. 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}
:show:

Here is my toggle-able content!
```

It results in the following:

Here is my toggle-able content!

Change the button hint text

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

togglebutton_hint = "Displayed when the toggle is closed."
togglebutton_hint_hide = "Displayed when the toggle is open."

Change the toggle icon color

You can apply some extra styles to the toggle button to achieve the look you want. This is particularly useful if the color of the toggle button does not contrast with the background of an admonition.

To style the toggle button, add a custom CSS file to your documentation and include a custom CSS selector like so:

// Turn the color red...
// ...with admonition toggle buttons
button.toggle-button {
  color: red;
}

// ...with content block toggle buttons
.toggle-button summary {
  color: red;
}

Printing behavior with toggle buttons

By default sphinx-togglebutton will open all toggle-able content when you print. It will close them again when the printing operation is complete. To disable this behavior, use the following configuration in conf.py:

togglebutton_open_on_print = False