configuration.md

Configuration

JupyterLite-sphinx can be configured in your conf.py file by setting some global Python variables:

JupyterLite content

You can embed custom content (notebooks and data files) in your JupyterLite build by providing the following config:

jupyterlite_contents = ["./path/to/my/notebooks/", "my_other_notebook.ipynb"]

jupyterlite_contents can be a string or a list of strings. Each string is expanded using the Python glob.glob function with its recursive option. See the glob documentation and the wildcard pattern documentation for more details.

JupyterLite dir

By default, jupyterlite-sphinx runs the jupyter lite build command in the docs directory, you can overwrite this behavior and ask jupyterlite to build in a given directory:

# Build in the current directory
jupyterlite_dir = "/path/to/your/lite/dir"

Pre-installed packages

In order to have Python packages pre-installed in the kernel environment, you can use jupyterlite-xeus, with the xeus-python kernel.

You would need jupyterlite-xeus installed in your docs build environment.

You can pre-install packages by adding an environment.yml file in the docs directory, with xeus-python defined as one of the dependencies. It will pre-build the environment when running the jupyter lite build.

Furthermore, this automatically installs any labextension that it finds, for example, installing ipyleaflet will make ipyleaflet work without the need to manually install the jupyter-leaflet labextension.

Say you want to install NumPy, Matplotlib and ipycanvas, it can be done by creating an environment.yml file with the following content:

name: xeus-python-kernel
channels:
  - https://repo.mamba.pm/emscripten-forge
  - https://repo.mamba.pm/conda-forge
dependencies:
  - numpy
  - matplotlib
  - ipycanvas

JupyterLite configuration

You can provide custom configuration files to your JupyterLite deployment for build-time configuration and settings overrides.

The build-time configuration can be used to change the default settings for JupyterLite, such as changing which assets are included, the locations of the assets, which plugins are enabled, and more.

The runtime configuration can be used to change the settings of the JupyterLite deployment after it has been built, such as changing the theme, the default kernel, the default language, and more.

# Build-time configuration for JupyterLite
jupyterlite_config = "jupyter_lite_config.json"
# Override plugins and extension settings
jupyterlite_overrides = "overrides.json"

Setting default button texts for the JupyterLite, NotebookLite, Replite, and Voici directives

When using the :new_tab: option in the JupyterLite, NotebookLite, Replite, and Voici directives, the button text defaults to "Open as a notebook", "Open in a REPL", and "Open with Voici", respectively.

You can optionally the button text on a global level for these directives by setting the following values in your conf.py file:

jupyterlite_new_tab_button_text = "My custom JupyterLite button text"
notebooklite_new_tab_button_text = "My custom NotebookLite button text"
replite_new_tab_button_text = "My custom Replite button text"
voici_new_tab_button_text = "My custom Voici button text"

You can override this text on a per-directive basis by passing the :new_tab_button_text: option to the directive. Note that this is compatible only if :new_tab: is also provided.

REPL code auto-execution with the Replite directive

It is possible to control whether code snippets in REPL environments automatically executes when loaded. For this, you may set replite_auto_execute = False globally in conf.py with (defaults to True if not present), or override it on a per-directive basis with :execute: True or :execute: False.

Strip particular tagged cells from IPython Notebooks

When using the NotebookLite, JupyterLite, or Voici directives with a notebook passed to them, you can strip particular tagged cells from the notebook before rendering it in the JupyterLite console.

This behaviour can be enabled by setting the following config:

strip_tagged_cells = True

and then by tagging the cells you want to strip with the jupyterlite_sphinx_strip tag in the JSON metadata of the cell, like this:

"metadata": {
  "tags": [
    "jupyterlite_sphinx_strip"
  ]
}

This is useful when you want to remove some cells from the rendered notebook in the JupyterLite console, for example, cells that are used for adding reST-based directives or other Sphinx-specific content. It can be used to remove either code cells or Markdown cells.

For example, you can use this feature to remove the toctree directive from the rendered notebook in the JupyterLite console:

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "tags": [
          "jupyterlite_sphinx_strip"
        ]
      },
      "source": [
        "# Table of Contents\n",
        "\n",
        "```{toctree}\n",
        ":maxdepth: 2\n",
        "\n",
        "directives/jupyterlite\n",
        "directives/notebooklite\n",
        "directives/replite\n",
        "directives/voici\n",
        "directives/try_examples\n",
        "full\n",
        "changelog\n",
        "```"
      ]
    }
  ]
}

where the cell with the toctree directive will be removed from the rendered notebook in the JupyterLite console.

In the case of a MyST notebook, you can use the following syntax to tag the cells:

+++ {"tags": ["jupyterlite_sphinx_strip"]}

# Heading 1

This is a Markdown cell that will be stripped from the rendered notebook in the
JupyterLite console.

+++

```{code-cell} ipython3
:tags: [jupyterlite_sphinx_strip]

# This is a code cell that will be stripped from the rendered notebook in the
# JupyterLite console.
def foo():
    print(3)
```

```{code-cell} ipython3
# This cell will not be stripped
def bar():
    print(4)
```

The Markdown cells are not wrapped, and hence the +++ and +++ markers are used to indicate where the cells start and end. For more details around writing and customising MyST-flavoured notebooks, please refer to the MyST Markdown overview.

Note that this feature is only available for the NotebookLite, JupyterLite, and the Voici directives and works with the .md (MyST) or .ipynb files passed to them. It is not implemented for the TryExamples directive.

Disable the .ipynb docs source binding

By default, jupyterlite-sphinx binds the .ipynb source suffix so that it renders Notebooks included in the doctree with JupyterLite. This is known to bring warnings with plugins like sphinx-gallery, or to conflict with nbsphinx.

You can disable this behavior by setting the following config:

jupyterlite_bind_ipynb_suffix = False

Suppressing JupyterLite logging

jupyterlite can produce large amounts of output to the terminal when docs are building. By default, this output is silenced, but will still be printed if the invocation of jupyter lite build fails. To unsilence this output, set

jupyterlite_silence = False

in your Sphinx conf.py.

Additional CLI arguments for jupyter lite build

Additional arguments can be passed to the jupyter lite build command using the configuration option jupyterlite_build_command_options in conf.py. The following example shows how to specify an alternative location for the xeus kernel's environment.yml file as discussed here.

jupyterlite_build_command_options = {
    "XeusAddon.environment_file": "jupyterlite_environment.yml",
    }

This causes the additional option --XeusAddon.environment_file=jupyterlite_environment.yml to be passed to jupyter lite build internally within jupyterlite-sphinx. Note that one does not include the leading dashes, --, in the keys.

The options --contents, --output-dir, and --lite-dir cannot be passed to jupyter lite build in this way. These can instead be set with the jupyterlite_contents and thejupyterlite_dir configuration options described above.

This is an advanced feature and users are responsible for providing sensible command line options. The standard precedence rules between jupyter lite build CLI options and other means of configuration apply. See the jupyter lite CLI documentation for more info.