manual_teachbooks/book/features/jupyterlite/including-jupyterlite.md

How to add JupyterLite to a page

There are three different JupyterLite directives that you can include in your web page:

1. retrolite: this embeds the old Jupyter Notebook environment in your page. This is a good one if you want students to program things on you page, since it allows students to edit and execute cells.
2. jupyterlite: this embeds a JupyterLab environment in your page.
3. replite: this variant provides an environment similar to the regular IPython kernel.

Below are examples demonstrating how to include each variant. Note that the jupyterlite-sphinx extension is designed for use with .rst files (Restructured Text). Luckily, MyST provides a convenient directive that allows us to include Restructured Text content in a regular .md file.

:class: tip
This feature doesn't display in a book that is viewed locally via your browser, unless you set up a local webserver (instructions [here](setup-local-server)).

retrolite

To embed a Jupyter Notebook environment in your book, include the following directive:

```{eval-rst}
.. retrolite::
```

You can also include you own notebook for students to work with. To do so, add it to the directive like this:

```{eval-rst}
.. retrolite:: wave.ipynb
```

Finally, there are some formating options available:

```{eval-rst}
.. retrolite:: wave.ipynb
    :width: 100%            # The width of the box
    :height: 500px          # The height of the box
    :prompt: Click me!      # Instead of loading the kernel immediately, show a button 
                              that activates the kernel on clicking. 
    :prompt_color: #00aa42  # Color of the prompt button
```

Here is the final result of the directive above:

.. retrolite:: wave.ipynb
    :width: 100%
    :height: 500px
    :prompt: Click me!
    :prompt_color: #00aa42

jupyterlite

To embed a JupyterLab environment in your book, simply change out retrolite for jupyterlite:

```{eval-rst}
.. jupyterlite::
    :width: 100%
    :height: 500px
    :prompt: Click me!
    :prompt_color: #00aa42
```

Here is the final result:

.. jupyterlite:: 
    :width: 100%
    :height: 500px
    :prompt: Click me!
    :prompt_color: #00aa42

replite

The replite directive provides a REPL environment (Read-Evaluate-Print-Loop) that is very similar to IPython in the terminal. Here's how you can include it:

```{eval-rst}
.. replite::
    :width: 100%
    :height: 500px
    :prompt: Click me!
    :prompt_color: #00aa42
```

You can't include a notebook in a replite environment, but you can pass it some code that executes once the kernel is loaded:

```{eval-rst}
.. replite::
    :width: 100%
    :height: 500px
    :prompt: Click me!
    :prompt_color: #00aa42

    print("Hello, world!")
```

Here's what it looks like:

.. replite::
    :width: 100%
    :height: 500px
    :prompt: Click me!
    :prompt_color: #00aa42

    print("Hello, world!")