marimo + Jupyter Book

marimo is a reactive Python notebook that can be embedded in static documents. This repo is a Jupyter Book executable plugin that lets you write marimo cells in MyST pages and publish a static book whose controls, tables, plots, SQL results, and dependent cells still respond in the browser.

Requires Python 3.10+. The package installs marimo for page execution.

Quick Start

1. Install the plugin in the same environment as Jupyter Book:

pip install jupyter-book-marimo

For uv-managed projects, use:

uv add jupyter-book-marimo

2. Register the executable plugin in myst.yml:

project:
  plugins:
    - type: executable
      path: .venv/bin/jupyter-book-marimo

Use the executable path that matches your environment. In this repo's docs site, the docs live in docs/, so the path is ../.venv/bin/jupyter-book-marimo.

3. Edit a MyST page:

---
title: My reactive page
---

# A reactive page

```{marimo} python
import marimo as mo

slider = mo.ui.slider(start=1, stop=10, step=1, label="items")
slider
```

```{marimo} python
mo.md(f"The slider is set to **{slider.value}**.")
```

Set page defaults or page-local dependencies with {marimo-config}:

```{marimo-config}
:echo: true
:pyproject: |
  requires-python = ">=3.10"
  dependencies = ["pandas"]
```

4. Build the book:

jupyter-book build --html

Features

jupyter-book-marimo uses marimo islands so reactive notebook content can live between ordinary book sections. The plugin supports Python, SQL, and Markdown cells, page-level execution defaults, page-local dependencies, custom styling hooks, and static HTML output that hydrates into interactive marimo components on load.

Docs

Read the user docs at marimo-team.github.io/jupyter-book-marimo.

For the full local development workflow, see CONTRIBUTING.md.