Welcome to Sphinx-Marimo Documentation#

This documentation demonstrates the Sphinx-Marimo extension, which allows you to embed interactive Marimo notebooks directly in your Sphinx documentation.

Contents:

Introduction#

Sphinx-Marimo enables you to include Marimo notebooks in your documentation with WASM support, similar to how Jupyter-Lite works. This means your notebooks run entirely in the browser without requiring a server.

Quick Example#

Here’s a simple Marimo notebook embedded in the documentation:

Features#

  • Zero-config WASM deployment: Notebooks are automatically built to WASM during documentation build

  • Interactive notebooks: Full Marimo interactivity in your documentation

  • Static site compatible: Works with GitHub Pages, Read the Docs, and other static hosts

  • Customizable embedding: Control size, theme, and styling of embedded notebooks

  • Click-to-load: Notebooks only load when clicked for better performance

Installation#

Install the extension using pip or uv:

pip install sphinx-marimo

Or with uv:

uv add sphinx-marimo

Configuration#

Add the extension to your conf.py:

extensions = [
    'sphinx_marimo',
    # ... other extensions
]

# Optional configuration
marimo_notebook_dir = 'notebooks'  # Directory containing .py Marimo notebooks
marimo_default_height = '600px'
marimo_default_width = '100%'

# Parallel build and caching (default values shown)
marimo_parallel_build = True       # Enable parallel notebook building
marimo_n_jobs = -1                  # Number of parallel jobs (-1 = auto-detect CPU cores)
marimo_cache_notebooks = True       # Enable caching to speed up repeated builds

# Click-to-load configuration (multiple modes available)
marimo_click_to_load = True        # Options: False, True/"overlay", "compact"
marimo_load_button_text = "Load Interactive Notebook"

Usage#

Use the marimo directive in your RST files:

.. marimo:: path/to/notebook.py
   :height: 800px
   :width: 100%
   :theme: light

Indices and tables#