Add "how to include JupyterLite" + demo notebook

book/cookbook/jupyterlite/including-jupyterlite.md

@@ -0,0 +1,103 @@
+# Adding `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. This is probably the best solution if you want to include small, interactive pieces of content, like a plot with sliders. 
+
+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. 
+
+
+## `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:
+
+```{eval-rst}
+.. 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:
+
+```{eval-rst}
+.. jupyterlite:: 
+    :width: 100%
+    :height: 500px
+    :prompt: Click me!
+    :prompt_color: #00aa42
+```
+
+## `replite`
+
+This is probably the cleanest solution when you want to do something simple, like a `matplotlib` plot with some `ipywidgets` sliders. 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:
+
+```{eval-rst}
+.. replite::
+    :width: 100%
+    :height: 500px
+    :prompt: Click me!
+    :prompt_color: #00aa42
+
+    print("Hello, world!")
+```