Install & Compatibility
Where this runs
tested against v0.4.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.7s · import 0.000s · 93MB
98MB installed
● package 98MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Extension Configuration
✓ extensions = ['sphinx_togglebutton'] # in conf.py
sphinx-togglebutton is a Sphinx extension, not a Python module imported into application code. It's added to the 'extensions' list in Sphinx's conf.py.
To enable sphinx-togglebutton, add 'sphinx_togglebutton' to the `extensions` list in your Sphinx project's `conf.py` file. Once enabled, you can make admonitions collapsible by adding `:class: dropdown` to them, or hide arbitrary blocks of content using the `.. toggle::` directive.
# conf.py
extensions = [
'sphinx_togglebutton',
# ... other extensions
]
# example.rst or example.md
.. note:: Click to toggle
:class: dropdown
This content is initially hidden and can be toggled by clicking the admonition title.
.. toggle:: Show/Hide Arbitrary Content
This entire block of content, including paragraphs and other directives,
will be hidden behind a toggle button.
- Item 1
- Item 2
Debug
Known issues
breakingThe v0.3.0 and v0.3.2 releases introduced significant visual changes to the toggle buttons and icons. Custom CSS styling targeting older versions (pre-0.3.0) may need adjustment, as the design and layout of the toggle elements were overhauled.fixReview your custom CSS for selectors targeting sphinx-togglebutton elements and update them to match the new HTML structure introduced in v0.3.0. Refer to the official documentation for the latest CSS classes and structure.
affects: 0.3.0, 0.3.1, 0.3.2
gotchaBy default, `sphinx-togglebutton` applies toggle functionality to elements matching `.toggle` or `.admonition.dropdown` CSS selectors. If you wish to apply toggles to other custom elements or classes, you must explicitly configure the `togglebutton_selector` in `conf.py`.fixTo customize the target selectors, add `togglebutton_selector = ".my-custom-class, #my-id"` to your `conf.py`.
affects: All versions
gotchaWhen a Sphinx documentation page containing toggle buttons is printed, all toggle-able content is opened by default. This might not be the desired behavior for all use cases.fixTo disable this automatic expansion on print, set `togglebutton_open_on_print = False` in your `conf.py` file.
affects: All versions
Upgrade
Version history
0.4.5latest on PyPI · released Mar 27, 2026
Audit
Dependencies
No dependency data recorded yet.