API Reference#

This page documents the Sphinx-Marimo extension API.

Extension Setup#

sphinx_marimo.setup(app)#

Main setup function for the Sphinx extension.

Parameters:

app (sphinx.application.Sphinx) – Sphinx application instance

Returns:

Extension metadata dictionary

Return type:

dict

This function is called by Sphinx during initialization. It registers:

  • Configuration values

  • The marimo directive

  • Event handlers for building notebooks

  • Static CSS and JavaScript files

Configuration Values#

The following configuration values can be set in conf.py:

marimo_notebook_dir#

Directory containing Marimo notebook files (relative to source directory).

Type:

str

Default:

“notebooks”

marimo_build_dir#

Directory for build artifacts (relative to output directory).

Type:

str

Default:

“_build/marimo”

marimo_output_dir#

Directory for static files (relative to output directory).

Type:

str

Default:

“_static/marimo”

marimo_default_height#

Default height for embedded notebooks.

Type:

str

Default:

“600px”

marimo_default_width#

Default width for embedded notebooks.

Type:

str

Default:

“100%”

Click-to-Load Configuration#

marimo_click_to_load#

Control how notebooks are loaded. Options:

  • False - Notebooks load immediately (traditional behavior)

  • True or "overlay" - Full-height overlay with centered button

  • "compact" - Space-saving button that expands when clicked

Type:

bool or str

Default:

True

marimo_load_button_text#

Text to display on the load button when click-to-load is enabled.

Type:

str

Default:

“Load Interactive Notebook”

Directive#

.. marimo:: notebook_path#

Embed a Marimo notebook in the documentation.

Param notebook_path:

Path to the notebook file (relative to marimo_notebook_dir)

Type notebook_path:

str

Options:

:height: (string)#

Height of the embedded iframe (e.g., “700px”, “80vh”)

:width: (string)#

Width of the embedded iframe (e.g., “100%”, “800px”)

:class: (string)#

Additional CSS classes to apply to the container

:theme: (string)#

Theme for the notebook (“light”, “dark”, or “auto”)

:click-to-load: (string)#

Override the global click-to-load setting for this specific notebook.

  • "false" - Load immediately

  • "true" or "overlay" - Full-height overlay with button

  • "compact" - Compact button that expands on click

:load-button-text: (string)#

Override the button text shown when click-to-load is enabled for this notebook. Only used when click-to-load is true.

Examples:

Basic usage:

.. marimo:: examples/my_notebook.py
   :height: 800px
   :width: 90%
   :theme: dark

Different click-to-load modes:

# Immediate loading (no button)
.. marimo:: quick_demo.py
   :height: 400px
   :click-to-load: false

# Full overlay with centered button
.. marimo:: analysis.py
   :height: 600px
   :click-to-load: overlay
   :load-button-text: Start Analysis

# Compact button that expands
.. marimo:: heavy_computation.py
   :height: 800px
   :click-to-load: compact
   :load-button-text: Run Heavy Computation