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:

This panel allows you to control the execution on the current page.
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.

The right-most button will take you to the fully interactive Jupyter Server.
Binder configuration options¶
By default, in-page computation uses a BinderHub service to provide computation.
Options for Binder configuration¶
key | required? | description | default |
---|---|---|---|
repo | required | The repository to use as a base image for your Jupyter server as a owner/reponame string or a fully qualified url. See Choose the repository for your kernel environment. | executablebooks/thebe-binder-base |
ref | optional | The git ref to use from the repository, allow you to target a specific branch, tag or commit. See Choose a branch or ref for your environment. | HEAD |
url | optional | The base url of the binder service to connect to. See Choose the BinderHub service for computation. | mybinder.org |
provider | optional | Tells thebe how to form urls for requesting binder services. Can be one of github , gitlab or git . See Choose a repository provider other than GitHub. | github |
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 .
Equivalent Syntax
The following cases are all equivalent:
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
A complete thebe.binder
configuration
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/
A complete thebe.binder
configuration
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
A complete thebe.binder
configuration
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>
A unique connection token must be supplied to connect to a local server
key | description | default |
---|---|---|
url | The base url of the Jupyter server you want to connect to | http://localhost:8888 |
token | The secret token string required by your Jupyter server |
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.
Securing a Jupyter server
If you intend to run a dedicated single user Jupyter server accessible over a network please carefully read and follow the advice provided by the Jupyter server team here.
MyST Websites will work best, be safer and be more robust when backed by Jupyter services such as BinderHub or JupyterHub.
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.
key | description | default |
---|---|---|
kernelName | The name of the kernel to request when starting a session | python |
disableSessionSaving | When false (default) any server settings received from binder will be cached in local storage. On page refresh or future page load the save session info will be used provided the session is still activate and the max age (86400s) has not been exceeded | false |
mathjaxUrl | Allows the default mathjax bundle loaded by the Jupyter Latex Typesetter to be changed | Mathjax 2.7.5 from cdnjs.cloudflare [1] |
mathjaxConfig | Allows the default mathjax configuration string to be changed | TeX-AMS_CHTML-full,Safe |
https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js