https://github.com/executablebooks/sphinx-togglebutton
Show and hide content with a button in Sphinx
https://github.com/executablebooks/sphinx-togglebutton
jupyter-book sphinx sphinx-doc sphinx-extension
Last synced: 8 months ago
JSON representation
Show and hide content with a button in Sphinx
- Host: GitHub
- URL: https://github.com/executablebooks/sphinx-togglebutton
- Owner: executablebooks
- License: mit
- Created: 2020-01-08T19:46:56.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2025-02-24T19:58:13.000Z (9 months ago)
- Last Synced: 2025-03-26T05:45:29.627Z (8 months ago)
- Topics: jupyter-book, sphinx, sphinx-doc, sphinx-extension
- Language: JavaScript
- Homepage: https://sphinx-togglebutton.readthedocs.io/en/latest/
- Size: 769 KB
- Stars: 46
- Watchers: 7
- Forks: 16
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starred - executablebooks/sphinx-togglebutton - Show and hide content with a button in Sphinx (others)
README
# sphinx-togglebutton
A small sphinx extension to make it possible to add a "toggle button" to
sections of your page. This allows you to:
- Collapse Sphinx admonitions (notes, warnings, etc) so that their content is hidden
until users click a toggle button.
- Collapse arbitrary chunks of content on your page with a `collapse` directive.
Installation
============
You can install `sphinx-togglebutton` with `pip`:
```bash
pip install sphinx-togglebutton
```
Usage
=====
In your `conf.py` configuration file, add `sphinx_togglebutton`
to your extensions list.
E.g.:
```python
extensions = [
...
'sphinx_togglebutton'
...
]
```
Now, whenever you wish for an admonition to be toggle-able, add the
`:class: dropdown` parameter to the admonition directive that you use.
For example, this code would create a toggle-able "note" admonition
that starts hidden:
```rst
.. note::
:class: dropdown
This is my note.
```
Clicking on the toggle button will toggle the item's visibility.
You may also **show the content by default**. To do so, add the `dropdown`
class *as well as* a `toggle-shown` class, like so:
```rst
.. note::
:class: dropdown, toggle-shown
This is my note.
```
You can also use **containers** to add arbitrary toggle-able code. For example,
here's a container with an image inside:
```rst
.. container:: toggle, toggle-hidden
.. admonition:: Look at that, an image!
.. image:: https://media.giphy.com/media/mW05nwEyXLP0Y/giphy.gif
```