toggle: Show/Hide Code Output

The toggle extension allows you to toggle between showing code with output or just code by itself in Quarto HTML documents by adding a convenient toggle button that appears when hovering over code blocks, similar to the copy button.

Important

GIF HERE

Installation

To install the toggle extension, follow these steps:

1. Open your terminal.

2. Execute the following command:

quarto add coatless-quarto/toggle

This command will download and install the extension under the _extensions subdirectory of your Quarto project. If you are using version control, ensure that you include this directory in your repository.

Quick Start

1. Add the filter to your document's YAML header:

---
title: "My Document"
format: html
filters:
  - toggle
---

2. Enable toggle for specific code cells by adding toggle: true:

```{python}
#| toggle: true
print("Hello, Python world!")
```

That's it! A toggle button will now appear when you hover over the code block.

Usage

At the top of your Quarto document, include the filters key with toggle specified in the YAML header:

---
title: "My Document"
format: html
filters:
  - toggle
---

This will allow the toggle extension to be applied to your document.

Cell-Level Configuration

To enable toggle functionality for a specific code cell, add the toggle: true attribute:

```{r}
#| toggle: true
print("Hello, R world!")
```

Hide Output by Default

Start with output hidden using the output-hidden attribute:

```{python}
#| toggle: true
#| output-hidden: true
import pandas as pd
print("This output is hidden by default")
```

Multi-Output Control

When code cells produce multiple outputs, you can control how the toggle buttons behave:

Individual Control (Default)

When output-sync: false, each output in a cell can be toggled independently. This is the default behavior.

```{r}
#| toggle: true
#| output-sync: false
print("Output 1")  # Individual toggle
print("Output 2")  # Individual toggle
plot(cars)         # Individual toggle
```

Synchronized Control

When output-sync: true, all outputs for a cell are toggled together with a single button:

```{r}
#| toggle: true
#| output-sync: true
print("Output 1")  # Any button controls all
print("Output 2")  # Any button controls all
plot(cars)         # Any button controls all
```

Document-Level Configuration

You can enable toggle functionality for all code cells in your document by adding the following to your YAML header:

---
title: "My Document"
format: html
toggle:
  output-toggle: true    # Enable toggle functionality
  output-hidden: false   # Show outputs initially (default)
  output-sync: false     # Individual control (default)
filters:
  - toggle
---

Configuration Options

Option	Type	Default	Description
output-toggle	boolean	false	Enable toggle functionality
output-hidden	boolean	false	Hide outputs initially
output-sync	boolean	false	Synchronize all outputs in cell

Important

To avoid confusion with the toggle document-level key, the document-level configuration uses output-toggle instead of toggle for enabling the toggle functionality globally.

Priority of Settings

• Cell-level settings override document-level settings
• If no cell-level setting is provided, document-level settings apply
• If neither is provided, toggle is not enabled for that cell

Help

To report a bug, please add an issue to the repository's bug tracker.

Want to contribute a feature? Please open an issue ticket to discuss the feature before sending a pull request.