Example notebook¶

This notebook serves as a proof of principle for marimo-md-export.

You can view the original notebook at examples/notebook.py. The command used to convert it to a docs page is the just docs command in justfile.

import marimo as mo
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import sys

Figures¶

x = np.linspace(0, 4 * np.pi, 300)
fig, ax = plt.subplots(figsize=(7, 3))
ax.plot(x, np.sin(x), label=r"$\sin(x)$")
ax.plot(x, np.exp(-x / 6) * np.sin(x), label=r"$e^{-x/6}\sin(x)$", ls="--")
ax.set_xlabel("x")
ax.legend()
fig

Tables¶

df = pd.DataFrame(
    {
        "Quantity": ["Mean", "Variance", "Skewness"],
        "sin(x)": [0.0, 0.5, 0.0],
        "damped": [
            round(float(np.mean(np.exp(-x / 6) * np.sin(x))), 4),
            round(float(np.var(np.exp(-x / 6) * np.sin(x))), 4),
            None,
        ],
    }
)
df

Console output¶

print(f"Number of points: {len(x)}")
print(f"x range: [{x[0]:.4f}, {x[-1]:.4f}]")
print(f"Mean of sin(x): {np.mean(np.sin(x)):.6f}")

Number of points: 300
x range: [0.0000, 12.5664]
Mean of sin(x): -0.000000

String output¶

Returning a string from a cell preserves escape sequences like as actual newlines in the exported markdown.

"Line one\nLine two\nLine three"

Line one
Line two
Line three

JSON outputs¶

Returning a dict or list from a cell produces a Python-style formatted output using pprint.

{"name": "damped sinusoid", "amplitude": 1.0, "decay_rate": 0.167}

{'amplitude': 1.0, 'decay_rate': 0.167, 'name': 'damped sinusoid'}

[round(float(xi), 4) for xi in x[:5]]

[0.0, 0.042, 0.0841, 0.1261, 0.1681]

{
    "experiment": "damped sinusoid",
    "parameters": {
        "amplitude": 1.0,
        "decay_rate": 0.167,
        "frequency": 1.0,
    },
    "results": {
        "samples": 300,
        "range": [0.0, 12.5664],
        "statistics": {
            "mean": 0.0,
            "variance": 0.5,
            "converged": True,
        },
    },
    "tags": ["oscillation", "damping", "physics"],
}

{'experiment': 'damped sinusoid',
 'parameters': {'amplitude': 1.0, 'decay_rate': 0.167, 'frequency': 1.0},
 'results': {'range': [0.0, 12.5664],
             'samples': 300,
             'statistics': {'converged': True, 'mean': 0.0, 'variance': 0.5}},
 'tags': ['oscillation', 'damping', 'physics']}

Errors¶

Cells that raise exceptions produce error output with traceback.

raise ValueError("This cell demonstrates error output handling")

Traceback (most recent call last):
  File "/tmp/marimo_2349/__marimo__cell_ZHCJ_.py", line 1, in 
    raise ValueError("This cell demonstrates error output handling")
ValueError: This cell demonstrates error output handling

exception: This cell demonstrates error output handling

Output written to sys.stderr is captured separately from stdout.

sys.stderr.write(f"Warning: computing over {len(x)} points\n")

Warning: computing over 300 points

35

SVG graphics¶

Inline SVG rendered via mo.Html.

mo.Html("""<svg xmlns="http://www.w3.org/2000/svg" width="200" height="100" viewBox="0 0 200 100">
<rect x="5" y="5" width="190" height="90" fill="#4a9eff" rx="10"/>
<text x="100" y="55" text-anchor="middle" fill="white" font-size="14">SVG Image</text>
</svg>""")

Multiple outputs¶

A cell with both console output and an expression result.

print(f"Computing statistics for {len(x)} points...")
np.mean(np.sin(x))

Computing statistics for 300 points...

np.float64(-2.3684757858670008e-17)

Long line outputs¶

This cell produces output with very long lines to demonstrate overflow wrapping.

print(
    "A very long line that exceeds the typical container width, stretching well beyond what fits on a single line. In this case the text should scroll, not wrap! "
)

A very long line that exceeds the typical container width, stretching well beyond what fits on a single line. In this case the text should scroll, not wrap! 

You can pass --overflow scroll to the CLI to switch the global behaviour from wrapping to scrolling. Note, however, that JSON outputs (lists, dicts, tuples) won't be affected by this.

You can also control overflow on a per-cell basis.

Add # @scroll to a cell to force horizontal scrolling for its output, regardless of the global --overflow setting.

# @scroll
print(
    "A very long line that exceeds the typical container width, stretching well beyond what fits on a single line. In this case the text should scroll, not wrap! "
)

A very long line that exceeds the typical container width, stretching well beyond what fits on a single line. In this case the text should scroll, not wrap! 

Suppressing outputs¶

Adding # @suppress to a cell prevents its output from appearing in the exported markdown.

# @suppress
print("This is just for debugging - no need to include in the docs!")