Integrating Jupyter based Computation

MyST allows you to connect a website directly to a Jupyter Kernel, enabling interactive computation on your page.

This allows you to do some amazing things with your MyST website like:

• Allow readers to recompute your notebooks for themselves, demonstrating the reproducibility of your work
• Provide a new level of interactive content via ipywidgets and ipywidgets backed libraries such as ipympl, ipyleaflet, etc...
• Connect to Binder based compute services
• 🚧 Compute using the in-browser pyodide WASM kernel (backed by JupyterLite)

Quick setup options¶

MyST uses thebe for Jupyter connectivity which can be enabled using default settings by adding a single key (thebe: true) to the project frontmatter in your myst.yml file.

version: 1
project:
  title: Geocomputing
  thebe: true
site:
  template: book-theme
  title: My Computational Website

When the boolean form of the thebe key is used, MyST will try to determine where to connect to from existing github and binder keys you may have on your project and is intended to allow for easy setup of a few key use cases. To go beyond or override these, you can provide various options in the thebe field.

Case - thebe: true and no github or binder keys are present¶

project:
  thebe: true

When thebe: true and no github or binder keys are present MyST will try to connect to a server using the default (local settings). To make this work you'll need to Start a local Jupyter server with the correct defaults or provide alternative direct connection options.

Note this is equivalent to:

project:
  thebe:
    server: true

Case - thebe: true and the github key is present¶

project:
  github: executablebooks/thebe-binder-base
  thebe: true

When thebe: true and the github key is present, MyST will attempt to connect to the public mybinder.org service using the repository information and a the default ref: HEAD. See Connecting to a Binder to point to a different binder service or changing repository details.

Note this is equivalent to:

project:
  github: executablebooks/thebe-binder-base
  thebe:
    binder: true

Case - thebe: true and the binder key is present¶

project:
  binder: https://mybinder.org/v2/gh/executablebooks/thebe-binder-base/HEAD
  thebe: true

When thebe: true and the binder key is present, MyST will use the binder information to establish a connection, the github field will be ignored.

Note this is also equivalent to:

project:
  binder: https://mybinder.org/v2/gh/executablebooks/thebe-binder-base/HEAD
  thebe:
    binder: true

🚧 Case - Using Pyodide & JupyterLite¶

thebe can provide access to the pyodide WASM kernel to enable in-browser computation. This uses in browser Jupyter server components developed as part of the JupyterLite project and will be extended in future to provide for different kernels.

The JupyterLite server and pyodide kernels can be activated using:

project:
  thebe:
    lite: true

This will load the server using the default options, to learn more about how using JupyterLite can affect site deployment and how environment setup works with pyodide see 🚧 Integrated compute with pyodide via JupyterLite

Disabling integrated compute¶

Easily disable integrated compute on your project by either setting thebe: false or removing the key altogether.

Disable integrated compute on a specific page in your website by adding thebe: false to the page frontmatter section.

Connecting to a Binder¶

When a the thebe.binder key contains a set of options, binder connections are enabled using the provided and default settings described below (github and binder keys at the project level are ignored). The most minimal form of configuration is where repository information is provided.

project:
  thebe:
    binder:
      repo: executablebooks/thebe-binder-base

This allows the repository information for integrated compute to be different to that used for the github badge on the website, for useful for example if the github badge is pointing to a organization or other repo.

project:
  thebe:
    binder:
      url: https://binder.myorganisation.com/services/binder/
      repo: executablebooks/thebe-binder-base
      ref: main
      provider: gitlab

Directly connecting to a Jupyter server¶

When the thebe.server key contains a set of options, direct connections to Jupyter use the provided (and default) settings, the most minimal form of configuration is:

project:
  thebe:
    server: true

Override the default settings using the following keys:

This allows you to connect to local servers on a different port, or across a private network and provide specific tokens to establish the connection, it is also useful in cases where this information is provided dynamically (for example after a JupyterHub server has been provisioned, however this requires additional infrastructure to deploy).

For more on working locally see Start a local Jupyter server.

🚧 Integrated compute with pyodide via JupyterLite¶

The JupyterLite server and pyodide kernels can be activated using:

project:
  thebe:
    lite: true

🚧 Local Development Mode¶

When working on a MyST site using the myst-cli, using a local Jupyter server connection makes a lot of sense and speeds up development. The local key allows you to enable and configure a local environment without having to change the other (remote) settings in your myst.yml file that will be used in your final deployment.

Local development using can be enabled by simply adding the local key, which will use default server options.

project:
  github: https://github.com/executablebooks/thebe-binder-base
    thebe:
      binder: true
      local: true

Further configure the local connection using the following options.

Start a local Jupyter server¶

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=test-secret --NotebookApp.allow_origin='*'

The command above is fine for local development and the token used should align with that provided in the project.thebe.token key.

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.

Reference¶

Complete options schema¶

project:
  thebe: undefined(false) | boolean | object
    lite: boolean
    binder: undefined(false) | boolean | object
      url: string (url)
      repo: string (org-name/repo-name)
      ref: string (valid git refs only?)
      provider: string (git | gitlab | github)
    server:  undefined(false) | boolean | object
      url: string (url)
      token: string (any)
    kernelName: string (any)
    disableSessionSaving: boolean (default: false)
    mathjaxUrl: string (url)
    mathjaxConfig: string (any)
    local: undefined(false) | boolean | object
      url: string (url)
      token: string (any)
      kernelName: string (any)

Additional options¶