marimo-md-export 0.5.0

A minimal solution for exporting marimo notebooks to markdown *with* rendered HTML outputs, designed for mkdocs/zensical sites.

marimo-md-export

A uv tool that wraps marimo export, extracts rendered outputs from the HTML export, and injects them into the markdown export. The result is a self-contained markdown document with embedded figures (as base64 <img> tags), tables (as GFM or HTML), and other cell outputs.

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

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 self-contained markdown page (with cell outputs injected), then builds the site.

Development

uv sync  # sync packages
just  # run lint, typecheck, test, build docs