Skip To Article

In-Page Execution

Connecting Jupyter Kernels to your MyST website

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:

myst.yml
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.

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.

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¶

keyrequired?descriptiondefault
reporequiredThe 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
refoptionalThe 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
urloptionalThe base url of the binder service to connect to. See Choose the BinderHub service for computation.mybinder.org
provideroptionalTells 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:

myst.yml
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 .

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:

myst.yml
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:

myst.yml
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:

myst.yml
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:

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

A unique connection token must be supplied to connect to a local server

keydescriptiondefault
urlThe base url of the Jupyter server you want to connect tohttp://localhost:8888
tokenThe 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.

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:

mypage.ipynb
---
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:

mypage.md
---
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.

keydescriptiondefault
kernelNameThe name of the kernel to request when starting a sessionpython
disableSessionSavingWhen 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 exceededfalse
mathjaxUrlAllows the default mathjax bundle loaded by the Jupyter Latex Typesetter to be changedMathjax 2.7.5 from cdnjs.cloudflare[1]
mathjaxConfigAllows the default mathjax configuration string to be changedTeX-AMS_CHTML-full,Safe
Footnotes¶
  1. https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js

MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication, part of Jupyter.