Quick Start¶

This guide will help you get started with using marimo inside MkDocs. There are two main ways to use marimo in your documentation:

Inline Code: Write Python code directly in your Markdown files using marimo islands
Playground Embed: Embed full marimo notebooks using the marimo playground

Prerequisites¶

Before you begin, make sure you have:

Installed the marimo plugin for MkDocs (see Installation)
Added the plugin to your mkdocs.yml file

Approach 1: Inline Code with marimo Islands¶

This is the simplest way to add interactive Python code to your documentation. Code is written directly in your Markdown files and executed in place.

Basic Example¶

```python {marimo}
2 + 2
```

By default, marimo executes the code and displays the result. On page load, marimo re-hydrates the cell state and executes the code again using WebAssembly.

Interactive Elements¶

```python {marimo}
import marimo as mo
name = mo.ui.text(placeholder="Enter your name", debounce=False)
name
```

```python {marimo}
mo.md(f"Hello, **{name.value or '__'}**!")
```

This produces:

Hello, __!

Approach 2: Embedding the marimo Playground¶

For more complex notebooks or when you want to provide a full notebook experience, you can embed the marimo playground. This approach requires the pymdown-extensions package.

pip install pymdown-extensions

Basic Playground Example¶

/// marimo-embed
    height: 400px
    mode: read
    app_width: wide

```python
@app.cell
def __():
    import marimo as mo
    name = mo.ui.text(placeholder="Enter your name")
    name
    return

@app.cell
def __():
    mo.md(f"Hello, **{name.value or '__'}**!")
    return
```

///

See Embedding the marimo playground for more details on this approach.

Which Approach Should You Choose?¶

Use Inline Code when:

You want to show simple, focused examples

Use Playground Embed when:

You want to show complete notebooks
You want users to be able to edit and experiment with the code
You want to embed existing .py notebooks

Working with Data¶

marimo integrates seamlessly with data analysis libraries. Here's an example using pandas:

```python {marimo}
import marimo as mo
import pandas as pd
data = pd.read_csv("https://huggingface.co/datasets/scikit-learn/Fish/resolve/main/Fish.csv")
mo.ui.table(data, selection=None)
```

Leveraging Reactivity¶

marimo's reactivity allows cells to update automatically when inputs or code changes. Here's a visualization example: