Getting Started¶

Installation¶

As a stand-alone tool¶

uv tool install marimo-md-export

pipx install marimo-md-export

The marimo-md-export command is then available globally on your system.

To run without installing:

uvx marimo-md-export notebook.py output.md

As a project dependency¶

Add to your pyproject.toml, for example under a docs dependency group:

uv add --group docs marimo-md-export

pip install marimo-md-export

[dependency-groups]
docs = [
  "marimo-md-export",
]

Usage¶

Write your notebook¶

This tool requires marimo notebooks in .py format (not .md).¹

Cell outputs are rendered in the export by default. If a cell produces output you don't want in the export, add # @suppress anywhere inside the cell.

Run the export¶

marimo-md-export is a CLI tool, built using Typer.

There are two required path-like arguments: the .py marimo notebook and the output path.

marimo-md-export notebook.py output.md

Run marimo-md-export --help to see all available options.

Options

Integrating with documentation sites¶

marimo-md-export is designed to produce markdown pages for static site generators like mkdocs or zensical. Both work identically for this purpose.

My suggestion is to add an extra build step that converts your notebook(s) before building the site (and to gitignore the outputs).

For example, this project uses the following just command to build the docs:

docs:
  marimo-md-export examples/notebook.py docs/example.md
  zensical build

This runs marimo-md-export to produce a self-contained markdown page (with cell outputs injected), then builds the site.

Gotchas¶

Existing files are overwritten by default.

marimo-md-export invokes marimo export as a subprocess. To ensure fully non-interactive operation, --force is always passed to marimo export, suppressing file-overwrite prompts.

Long output lines are a bit awkward.

By default, long output lines wrap within the container using CSS white-space: pre-wrap; overflow-wrap: break-word;. This keeps everything visible without scrolling but can break custom __str__ formatting.

Use --overflow scroll to switch to horizontal scrolling globally. This preserves the original formatting exactly but requires users to scroll horizontally for long lines.

You can also override the global default on a per-cell basis by adding # @scroll or # @wrap anywhere inside the cell (similar to # @suppress). The last marker in a cell wins if both are present.