Live code

Live code#

With live coding you can make your pages more interactive by adding live, executable code cells. This extension is already part of your TeachBooks book if you started from the template. If not, you can follow instructions in the manual to enable it. The template also includes a sample page with live code enabled, which you can find here for the website of the original template

With live code enabled, readers can run snippets directly in the browser, experiment with examples, and complete exercises in real time. This section will guide you through some of the main features available: additional cell tags have been developed that can be added to Python code cells in your book. These tags extend the existing Jupyter Book tags and allow you to control how cells behave when live execution is enabled.

Available custom tags#

  • disable-execution-cell disables the ability to execute the cell when live code is activated. This is useful if your notebook includes interactivity for only part of the cells.

  • disable-execution-page disables the ability to execute the entire page. This can be helpful if Python code is used to build a page but is not meant to be run by readers.

  • auto-execute-page automatically starts live coding when the page is opened, useful if you are using widgets.

  • thebe-init runs this cell automatically as soon as live coding starts.

  • thebe-remove-input-init is similar to thebe-init but hides the input from students while still executing it. (The regular remove-input tag will not work here, since it deletes the entire cell.)

Tip

Tags are case-sensitive. Use lowercase and match them exactly as shown above.

Creating a notebook#

There are two ways you can try this exercise, depending on whether you have an IDE installed. If you don’t know what an IDE is, or don’t have one installed, follow Option 2 below.

  1. In your repository, create a new notebook file in your book directory, e.g. book/live_code_tags.ipynb.

  2. To add a new code cell, use python and enter a simple code, for example:

```python
print("Hello world!")
```

With this setup, tags can be added by opening the cell metadata (in JupyterLab or Jupyter Notebook: View → Cell Toolbar → Tags).

  1. If you don’t have JupyterLab or VS Code installed, you can still add code in a markdown file. To make sure this is recognized as an interactive code cell, you need to add a Jupytext header. At the very top of your file (e.g. book/live_code_tags.md), add:

---
jupytext:
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.17.3
kernelspec:
  display_name: base
  language: python
  name: python3
---

  1. Now you can insert executable code cells like this:

```{code-cell} ipython3
print("Hello world!")
```

With this setup, tags can be added directly into the code cell using :tags:, for example:

```{code-cell} ipython3
:tags: ["hide-cell"]
print("Hello world!")
```

Trying the custom tags#

Now that you know how to create executable code cells, let’s explore the different custom tags available and see examples of how each one can control the behavior of your code when live execution is enabled.

disable-execution-cell#

  1. This tag is useful when you want a particular code cell to display content without being executed by readers. For example, let’s set up a new cell that prints the current date and time only once:

import datetime

# This prints the current date and time once
current_time = datetime.datetime.now()
print("This notebook was last updated at:", current_time)

Remember to add the tag disable-execution-cell locally via the cell metadata (View → Cell Toolbar → Tags).

```{code-cell} ipython3
:tags: ["disable-execution-cell"]

import datetime

# This prints the current date and time once
current_time = datetime.datetime.now()
print("This notebook was last updated at:", current_time)
```

  1. Commit and rebuild your book and visit the page — notice that this particular cell can no longer be run when live code is activated.

disable-execution-page#

  1. This tag is useful when you want all code cells on a page to be non-executable. This is handy if the code is used to build the page or provide context, but you don’t want readers to run it themselves. Add the tag disable-execution-page to any of the code cells in your file.

  2. Commit and rebuild your book and visit the page — none of the cells should be executable now.

Note

Remove this tag again before continuing, otherwise the next tags won’t have any effect.

auto-execute-page#

  1. This tag is useful when you want live code to start running automatically as soon as the page is opened. This is particularly helpful when using visualizations or interactive widgets that should initialize immediately. For example, let’s set up a plot:

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x)

plt.plot(x, y)
plt.title("Sine wave")
plt.show()

Remember to add the tag auto-execute-page to one of the cells via the cell metadata (View → Cell Toolbar → Tags).

```{code-cell} ipython3
:tags: ["auto-execute-page"]

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 100)
y = np.sin(x)

plt.plot(x, y)
plt.title("Sine wave")
plt.show()
```

  1. Commit and rebuild your book and visit the page — the plot should appear automatically without needing to click the “launch” button.

thebe-init#

  1. The thebe-init tag is useful when you want a specific cell to run automatically as soon as live coding starts. This is especially helpful for initializing variables that other cells depend on. For example, let’s initialize a dataset of student names and their scores:

# Initialize dataset
students = ["Alice", "Bob", "Charlie", "Diana"]
scores = [85, 92, 78, 90]

print("Initialized dataset with students and scores")

Remember to add the tag thebe-init locally via the cell metadata (View → Cell Toolbar → Tags).

```{code-cell} ipython3
:tags: ["thebe-init"]

# Initialize dataset
students = ["Alice", "Bob", "Charlie", "Diana"]
scores = [85, 92, 78, 90]

print("Initialized dataset with students and scores")
```

  1. Commit and rebuild your book and visit the page — as soon as live code starts, this cell will run by itself.

thebe-remove-input-init#

  1. This tag works similarly to thebe-init, but the input (code) is hidden from students, so they only see the output. This is useful when you want to initialize variables or datasets without showing implementation details. To try this, simply replace the previous tag thebe-init with thebe-remove-input-init in the same cell from the previous example.

  2. Commit and rebuild your book and visit the page — the cell will run automatically, but students will only see the output, not the code.

  3. When you are ready, commit your changes to the repository by clicking on the green Commit changes button.

  4. Add a commit message.

  5. To see your changes, go to Actions - The most recent workflow run overview.md / the commit message of the commit you just made - Wait for it to finish - In the summary, click on the link of your book shown in the table Branches deployed and under Primary book at root (getting bored of waiting? There’ll be exercising on doing this locally which prevents you from waiting).

  6. Do you see your change? If you don’t see it click CTRL+F5/Control+F5to refresh the page.

Check your understanding

Before moving on, make sure you understand the following:

  • How do you add tags to a code cell in your book?

  • Which tag disables execution for a single cell? For the whole page?

  • Which tag makes a page auto-start live code when opened?

  • What is the difference between thebe-init and thebe-remove-input-init?

Contents