In-Page Execution

In-page execution allows you to connect a live Jupyter kernel to your website, allowing you to add interactive visualizations and interactivity that is powered with a live kernel. This allows your readers to reproduce the outputs of your document in real-time, and to add more complex interactive content via tools like ipywidgets or Panel.

Here are a few back-ends that you can use to provide the computation for in-page execution:

• Binder (e.g., mybinder.org)
• WASM-based in-browser kernels with JupyterLite
• Local or remote Jupyter servers you spin up locally or via a service like JupyterHub

Enable in-page execution¶

To enable in-page execution, use the project.jupyter: true parameter like so:

version: 1
project:
  jupyter: true

By default, MyST will use mybinder.org to build and provide the environment for computation. It will use the thebe-binder-base repository to build the environment. If you have a GitHub repository defined for your project via project.github, then it will use that instead.

Launch in-page execution¶

To launch in-page execution on the page, press the “power” button at the top of the page content.

This will launch a Binder session (or, connect to a live Jupyter server based on your configuration). If you launch a Binder server, you’ll see a box in the bottom-right of the page showing the status of Binder launching your session.

You’ll know that execution is now available when the in-page execution panel is visible at the top of the page. It looks like this:

In addition, all cells on the page will execute when the server is available.

Launch into the interactive Jupyter server¶

To change the browser window to the fully interactive Jupyter server that is powering your computation, click the “Launch Jupyter Server Window” button to the right of the in-page execution panel.

Binder configuration options¶

By default, in-page computation uses a BinderHub service to provide computation.

Options for Binder configuration¶

Choose the repository for your kernel environment¶

To choose the repository that is used for your kernel, use the project.jupyter.binder.repo key. Here’s an example:

project:
  jupyter:
    binder:
      repo: https://github.com/binder-examples/requirements # default repo

By default, MyST will use the HEAD of the repository, which usually corresponds to the main branch. To choose a different branch, see .

project:
  jupyter: true

project:
  jupyter: 'binder'

project:
  jupyter:
    binder: true

project:
  jupyter:
    binder:
      repo: executablebooks/thebe-binder-base # default repo

project:
  jupyter:
    binder:
      repo: https://github.com/executablebooks/thebe-binder-base # default repo

Choose a branch or ref for your environment¶

To choose a branch or git ref other than the default (HEAD), use the ref key like so:

project:
  jupyter:
    binder:
      # ref can be the name of a branch or a commit hash
      ref: my-branch

Choose the BinderHub service for computation¶

To choose a BinderHub service other than mybinder.org, use configuration like so:

project:
  jupyter:
    binder:
      # The URL parameter controls the BinderHub serviec to use.
      url: https://binder.myorganisation.com/services/binder/

Choose a repository provider other than GitHub¶

To choose a git repository provider other than GitHub, use the provider key like so:

project:
  jupyter:
    binder:
      # See below for a list of available providers
      provider: gitlab

Configure my Binder repository environment¶

See the Binder documentation for instructions on how to set up your repository to have the environment you need. Binder uses the Reproducible Execution Environment Specification to turn repository contents into a reproducible environment.

Use a local or remote Jupyter server for in-page execution¶

If you have access to a Jupyter server that is already running (for example, by starting a server locally, or accessing a server via a JupyterHub), you can use this to provide in-page computation instead of Binder.

To use a server that is already running locally, use the jupyter.server key like so:

project:
  jupyter:
    server:
      url: http://localhost:8888/
      token: <your-secret-token>

Start a local Jupyter server for in-page computation¶

In addition to how you might normally start a JupyterLab session, it’s necessary to provide two additional command line options, as follows.

jupyter lab --NotebookApp.token=<your-secret-token> --NotebookApp.allow_origin='http://localhost:3000'

The command above is fine for local development. The token used should align with that provided in the project.thebe.token key and allow_origin should allow connections from your myst site preview, usually running on http://localhost:3000.

When starting a local Jupyter server for use with MyST it’s also important to understand your computational environment and ensure that the Jupyter instance has access to that with the dependencies it needs to run. This is achieved by following normal best practices for reproducible environment configuration, if you’re not familiar with these see REES.

Use JupyterLite and WebAssembly for in-page computation¶

The JupyterLite project allows you to ship a lightweight computational environment that runs fully in your browser. To use JupyterLite for your in-page computation, use the configuration below:

project:
  jupyter:
    lite: true

This will load the server using the default environment described in the JupyterLite docs. For more configuration options with JupyterLite, see Use JupyterLite and WebAssembly for in-page computation.

Enable or disable in-page computation on a single page¶

To configure in-page computation on a single page, use document frontmatter. For example:

To enable in-page computation on a single page, use configuration like so:

---
jupyter:
  binder:
    # If you had one page that needed an R kernel
    repo: https://github.com/binder-examples/r
---

My page content.

To disable in-page computation on a single page, use configuration like so:

---
jupyter: false
---

My page content.

Reference¶

Complete options schema¶

project:
  jupyter: undefined(false) | boolean | object | 'lite' | 'binder'
    lite: boolean
    binder: undefined(false) | boolean | object
      url: string (url)
      provider: string (git | gitlab | github | or custom)
      repo: string (org-name/repo-name | url | string)
      ref: string (undefined | string)
    server:  undefined | object
      url: string (url)
      token: string (any)
    kernelName: string (any)
    disableSessionSaving: boolean (default: false)
    mathjaxUrl: string (url)
    mathjaxConfig: string (any)

Additional options¶

The following keys can all be used under the project.jupyter configuration.