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: about 2 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 (over 4 years ago)
• Default Branch: master
• Last Pushed: 2023-12-22T17:02:00.000Z (9 months ago)
• Last Synced: 2024-07-14T13:33:15.632Z (2 months ago)
• Topics: jupyter-book, sphinx, sphinx-doc, sphinx-extension
• Language: JavaScript
• Homepage: https://sphinx-togglebutton.readthedocs.io/en/latest/
• Size: 765 KB
• Stars: 40
• Watchers: 10
• Forks: 13
• Open Issues: 10
• 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.

![Demonstration of Sphinx Togglebutton](https://user-images.githubusercontent.com/1839645/152654312-a72a320f-e1e0-40be-95ae-3ed34facc4d3.gif)

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

```