Integrate 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 jupyter: true (or thebe: true) to the project frontmatter in your myst.yml file.

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

When the field jupyter: true is set, MyST will try to determine where to connect to automatically by looking at the github field if you supplied one. Otherwise it will use the demo repository at https://github.com/executablebooks/thebe-binder-base along with mybinder.org to start a juptyer environment.

The intention here is to allow minimal setup to enable a few key use cases. To go beyond or override these, you can provide various options in the jupyter field which are documented below.

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

Jupyter Configuration Options¶

The following “cases” show different configuration options, aimed at different use cases. Look through these to find one that suits you purpose.

Case connect to binder with my own repo¶

jupyter: true and the github key is present

project:
  github: https://github.com/username/my-myst-article
  jupyter: 'binder'

When jupyter: 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.

project:
  github: https://github.com/username/my-myst-article
  jupyter: 'binder'

project:
  github: https://github.com/username/my-myst-article
  jupyter: true

project:
  github: https://github.com/username/my-myst-article
  jupyter:
    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:
  jupyter:
    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

project:
  jupyter:
    lite: true

Disabling integrated compute¶

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

Disable integrated compute on a specific page in your website by adding jupyter: 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:
  jupyter:
    binder:
      repo: username/my-myst-article

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:
  jupyter:
    binder:
      url: https://binder.myorganisation.com/services/binder/
      repo: executablebooks/thebe-binder-base
      ref: main
      provider: gitlab

Directly connecting to a (local) Jupyter server¶

The thebe.server key is used to provide options for direct connections to Jupyter, use the provided (and default) settings, the most minimal form of configuration is:

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

Both url and token must be provided to enable a server connection.

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).

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

🚧 Integrated compute with pyodide via JupyterLite¶

The JupyterLite server and pyodide kernels can be activated using:

project:
  jupyter:
    lite: true

Start a local Jupyter server for development purposes¶

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.

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¶