Metadata-Version: 2.4
Name: marimo-md-export
Version: 0.10.1
Summary: A minimal solution for exporting marimo notebooks to markdown *with* rendered HTML outputs, designed for mkdocs/zensical sites.
Keywords: marimo,markdown,documentation
Author: Joe Marsh Rossney
Author-email: Joe Marsh Rossney <17361029+jmarshrossney@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: lxml>=6.1.0
Requires-Dist: marimo>=0.23.3
Requires-Dist: typer>=0.25.0
Requires-Python: >=3.12
Project-URL: Homepage, https://jmarshrossney.github.io/marimo-md-export
Project-URL: Repository, https://github.com/jmarshrossney/marimo-md-export
Project-URL: Documentation, https://jmarshrossney.github.io/marimo-md-export
Description-Content-Type: text/markdown

# marimo-md-export

[![PyPI version](https://img.shields.io/pypi/v/marimo-md-export)](https://pypi.org/project/marimo-md-export/)
[![Python versions](https://img.shields.io/pypi/pyversions/marimo-md-export)](https://pypi.org/project/marimo-md-export/)
[![License](https://img.shields.io/pypi/l/marimo-md-export)](https://github.com/jmarshrossney/marimo-md-export/blob/main/LICENSE)
[![CI](https://github.com/jmarshrossney/marimo-md-export/actions/workflows/ci.yml/badge.svg)](https://github.com/jmarshrossney/marimo-md-export/actions/workflows/ci.yml)
[![Docs](https://github.com/jmarshrossney/marimo-md-export/actions/workflows/docs.yml/badge.svg)](https://jmarshrossney.github.io/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](https://jmarshrossney.github.io/marimo-md-export)**

## Quick start

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

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

Then run:

```sh
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](https://www.mkdocs.org/) or [zensical](https://zensical.org/).
Both work identically for this purpose.

**1. Add as a docs dependency:**

```sh
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](https://github.com/casey/just) command to build the docs:

```just
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

```sh
uv sync
```

A [`justfile`](justfile) provides the common tasks.

```sh
just     # runs everything
just -l  # list commands
```

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

Install [`pre-commit`](https://pre-commit.com/) so that the hooks in [`.pre-commit-config.yaml`](.pre-commit-config.yaml) run before each commit:

```sh
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.

