marimo-md-export

A CLI tool that wraps marimo export, extracts rendered outputs from the HTML export, and injects them into the markdown export. The result is a markdown document with tables (as GFM or HTML), console output, and other cell outputs, plus a sidecar assets directory for figures and the intermediate HTML notebook.

Full documentation

Quick start

Write your marimo .py notebook — cell outputs are rendered by default:

fig, ax = plt.subplots()
ax.plot(x, np.sin(x))
fig

Then run:

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

This writes output.md, plus output_assets/notebook.html and output_assets/figure-1.png (and so on).

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.

1. Add as a docs dependency:

uv add --group docs marimo-md-export

2. Add a build step that converts your notebook(s) before building the site.

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 markdown page (with cell outputs injected) and its assets directory, then builds the site.

Developer setup

Install the project and its development dependencies with

uv sync

A justfile provides the common tasks.

just     # runs everything
just -l  # list commands

If you don't have just on your PATH, prefix with uv run.

Install pre-commit so that the hooks in .pre-commit-config.yaml run before each commit:

uv tool install pre-commit
pre-commit install

Contributing

Contributions are welcome. Feel free to use Issues to ask questions or propose ideas.

Pull Requests should be opened against main. Please make sure the pre-commit hooks are passing and just runs without complaints.