Export notebook as markdown with output

[himalayahall]

Description

Ability to export a notebook, together with all its output, would be great. It would make it easy to share a fully materialized notebook with users who may not be able to(or bothered to) install Marimo or Jupyter and run it themselves.

Suggested solution

I have used the publishing capabilities of RStudio and it makes like a whole lot easier than running a chain of command line tools to get the job done. Would be great to have something like it in Marimo!

Alternative

No response

Additional context

No response

[mscolnick]

This is already possible with HTML and ipynb:

marimo export html notebook.py -o notebook.html
# and 
marimo export ipynb notebook.py -o notebook.ipynb --include-outputs

or am i misunderstanding?

[akshayka]

@himalayahall — here is a full guide on exporting to other formats, with outputs: https://docs.marimo.io/guides/exporting/.

We also have a variety of ways to publish interactive notebooks to the web: https://docs.marimo.io/guides/publishing/

I believe this solves your issue but feel free to re-open if not.

[himalayahall]

Ability to export notebooks in MD format WITH output would allow users to publish the notebook as README.md for GitHub repos.

Currently, Marimo export for MD does not include notebook output.

[akshayka]

Got it, markdown specifically. Yes, you're right we're missing that, and it would be a nice addition.

[mscolnick]

@himalayahall, would you expect "markdown versions" of certain outputs? for example, what would you want a slider to look like? what about a table or chart? what about an image?

couple approaches:

• could just pure html (no js or css)
• only display the outputs when _repr__markdown_ is implemented
• charts and images are converted to base64 data-uri (but this makes the markdown very noisy)

[ericmjl]

@mscolnick if I may chime in please, I think for Markdown output, the minimal use case to solve for might be just outputting images as PNG while referencing them in the output markdown file, while also rendering dataframe tables as static tables (according to whatever gets rendered). I think it's possible that doing so will help solve a vast majority of use cases for outputting markdown while executing. As for other things that have a __repr_html__ or __repr_markdown__, perhaps those can be progressively added in?

The job that I know I'd love to get done with this feature would be to write my notebook in Marimo, export as Markdown, and drop it into my blog as a post.

[almereyda]

One workaround could be to use https://github.com/marimo-team/quarto-marimo/ by @dmadisetti, which was adopted as a marimo-team project after an initial demonstrator (https://github.com/marimo-team/marimo/issues/1083#issuecomment-2053703326).

Some outputs seem to be created with it (https://github.com/marimo-team/quarto-marimo/issues/10).

[zzehli]

this would be so helpful as it allow people to read the output directly. html files are just not readable as plain files.

[mscolnick]

@zzehli, @almereyda does https://github.com/marimo-team/quarto-marimo/ work for you? I am curious what is missing?

[Ar4l]

No, it requires dependencies like quarto. I see there's similar support for Mkdocs in the works – point still stands. I get the vibe that marimo is stressing interactivity, but this part of the ecosystem is simply not there yet (though I am eagerly awaiting the day). And several use-cases come to mind where a more flexible, simpler markdown export seems suitable.

What I think others (and myself) look for is summarised as: we want to be able to view our marimo notebooks, with outputs, in code repositories (and offline). The current approach is to write markdown files on the side, but if all the textual content can be shared with Marimo notebooks, why not just provide an option to export it statically with no runtime requirements?

So, requirements in 3 longer points:

1. Version-controllable documentation. The current static export as html fails here for the same reason that marimo exists as alternative to jupyter.
2. No forced dependencies. Just plain old CommonMark so it seamlessly integrates with the status-quo of markdown for documentation that all major platforms support.
3. No runtime to view something static? I consider a browser to be a runtime, especially if it is loading things from a CDN.

[akshayka]

@Ar4l @zzehli @ericmjl @himalayahall

Here is a repository that shows how to do what (I think) you want, with marimo and nbconvert.

https://github.com/akshayka/test-markdown-export/

This does involve running multiple commands, but I wanted to get your feedback on which of the two options in the repo you prefer before we design a batteries included experience.

• intro.md: images stored in a separate folder, and the markdown file references them. Version controllable, but not a single file.
• intro_with_inline_images.md: images inlined with base64. Not easily version controllable, but a single file.

[Ar4l]

Hey thanks for the prompt response. Indeed it's what I would want. I think the simplest case would be to have the intro.md version, it ticks the boxes.

As it's serving as static documentation counterpart to the notebook, it would be amazing if there's just a toggle in the UI that automatically updates the markdown/images when cells are ran. Bonus points if tables are also included btw :)

Also, I can foresee different users have different preferences regarding where to place the images, and I can also see the merit in having everything in one single file – it's easier for sharing, what I think @himalayahall is actually aiming for. It may require some customisation options down the line.

[zzehli]

I don't have a strong preference. Lots of my use case is to look at someone else's notebook results without running them, often on Github. I think GH is able to render your image links on a separate location with md files.

[riziles]

Just chiming in here. One thing I don't like about marimo export ipynb is that it converts SQL cells to Python function calls ala mo.sql('select * from something'). It would be great if we could convert a Marimo file to Markdown with outputs and still retain SQL cells as fenced SQL code blocks. I like Quarto, but the Quarto extension is overkill for this use case.

[riziles]

... also, the Quarto extension doesn't seem to work at all for PDFs.

[dmadisetti]

@riziles can you open up an issue in the quarto extension repo with some more details? PDFs have been reported to work recently

[riziles]

@dmadisetti , honestly, I have a lot of issues with the Quarto extension, most of which seem to be related to using pixi instead of uv. I've spent many hours trying to troubleshoot. Unfortunately, I have to get some other stuff done now, but I can try to revisit next weekend. All that said, being able to include outputs (specifically: the tables generated by SQL cells) when exporting markdown would probably solve my use case.

[dmadisetti]

Ah. Yes, the quarto extension is written with UV as the main backbone on mind. I'm surprised you were even able to get it to run with just pixi without tinkering with it.