Skip to article content

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
  title: Geocomputing
  jupyter: true
  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 along with 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.

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

  jupyter: 'binder'

When jupyter: true and the github key is present, MyST will attempt to connect to the public 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.

🚧 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:

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

      repo: username/my-myst-article

A minimal thebe.binder configuration with the required repo field

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.

      repo: executablebooks/thebe-binder-base
      ref: main
      provider: gitlab

A complete thebe.binder configuration

reporequiredThe repository to use as a base image for your Jupyter server as a owner/reponame string or a fully qualified urlexecutablebooks/thebe-binder-base
urloptionalThe base url of the binder service to connect
refoptionalThe git ref to use from the repository, allow you to target a specific branch, tag or commitHEAD
provideroptionalTells thebe how to form urls for requesting binder services. Can be one of github, gitlab or git.github

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:

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

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

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

urlThe base url of the Jupyter server you want to connect tohttp://localhost:8888
tokenThe secret token string required by your jupyter server

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:

    lite: true

Minimal configuration for enabling JupyterLite

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.


Complete options schema

  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

kernelNameThe name of the kernel to request when stating 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 bindle loaded by the Juptyer 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
MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication