{"id":6247,"library":"sphinx-togglebutton","title":"Sphinx Toggle Button","description":"Sphinx Toggle Button is a Sphinx extension that enables users to add toggle functionality to documentation, allowing them to collapse or expand sections of content and admonitions. The library is actively maintained, with frequent patch releases addressing fixes and minor releases introducing new features. The current version is 0.4.5.","status":"active","version":"0.4.5","language":"en","source_language":"en","source_url":"https://github.com/executablebooks/sphinx-togglebutton","tags":["sphinx","documentation","toggle","collapse","admonition","extension"],"install":[{"cmd":"pip install sphinx-togglebutton","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"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.","symbol":"Extension Configuration","correct":"extensions = ['sphinx_togglebutton'] # in conf.py"}],"quickstart":{"code":"# conf.py\nextensions = [\n    'sphinx_togglebutton',\n    # ... other extensions\n]\n\n# example.rst or example.md\n\n.. note:: Click to toggle\n   :class: dropdown\n\n   This content is initially hidden and can be toggled by clicking the admonition title.\n\n\n.. toggle:: Show/Hide Arbitrary Content\n\n   This entire block of content, including paragraphs and other directives,\n   will be hidden behind a toggle button.\n\n   - Item 1\n   - Item 2\n","lang":"python","description":"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."},"warnings":[{"fix":"Review 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.","message":"The 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.","severity":"breaking","affected_versions":"0.3.0, 0.3.1, 0.3.2"},{"fix":"To customize the target selectors, add `togglebutton_selector = \".my-custom-class, #my-id\"` to your `conf.py`.","message":"By 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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To disable this automatic expansion on print, set `togglebutton_open_on_print = False` in your `conf.py` file.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}