export markdown

[lewisl]

A useful capability is writing a report on research or even just documenting the code. The exported notebook is a good starting point but usually can't stand as a finished work. So, the export needs to be editable.

The exported pdf looks nice, but is not editable.

The exported html is massively complicated by styles, fragmentation, and javascript. Typora, the best markdown tool doesn't barf, which is amazing enough. But, the results in innumerable spurious lines because of the structure of the input html.

Since the input text is already markdown, all that is needed is to capture output cells and then create a single markdown document, rather than cell-by-cell.

That would be a good starting point for editing a final report. It seems that there must be a cell-by-cell data structure that can easily be used.

[fonsp]

Thanks for the tip! Can you try to rephrase your issue as a statement of a problem, rather than a direct feature request? Try to emphasize the problem you face, not the solution you suggest.

[lewisl]

I think it’s clear. I would like an editable output to enhance as a report with additional content and formatting, starting with the notebook including code, text in the notebook, and cell output—particularly plots.

• Lewis

[fonsp]

Why not keep the notebook file as an editable file? That way you can not just edit the markdown, but also the code to generate plots!

[Omar-Elrefaei]

I think @lewisl would like to edit a report.md file that has backtick-ed julia code instead of the report.jl file with md"Documentation" cells.

I can see why that would be useful. A person might prefer to use their own specialized markdown writing setup (preview pane, wysiwyg, md specific shortcut...etc) to write a long-form report instead of being limited to pluto's editing capabilities.

[lewisl]

That gets part way. Obviously, the code is present in the editable .jl and in the notebook. The code file can be run in Julia REPL, but the stop at each cell doesn’t occur—the code runs lickety-split, but all that is left is whatever is displayed at the end. (Block breaks can be introduced using VS Code and the Julia plugin as ## <bunch o’ code> ##. But, that is sort of recreating the notebook. Similarly, one could just step through the code and capture plots and paste them in (the VS Code plugin maintains a plot collection for an entire session—so stopping is not actually needed). But, all of this seems like re-creating what the notebook output, doesn’t it? Can you point out a reasonably easy way to capture the outputs in the editable .jl file when running it? That would serve.

The goal is to have the plots and other output in place along with the original md””” “”” of the notebook. The notebook output serves as the first draft of the report. Additions are made that are just to supplement the material that accompanies running a model through various cases. Additionally, formatting can be improved with the use of a document oriented css, such as the stylesheets supplied with Typora.

I am going to fork and play with the cells array—it would seem to have everything needed already. Creating markdown that includes output is actually easier than creating pdf or html. Compared to your code that creates html, none of the js or css or html tagging is needed. It’s a matter of appending text chunks cell by cell, adding image links for the plots (or other images), and packaging it all in one directory and saving it. Sorry to proceed to solutions: solutions meet tangible goals—why we call them “solutions.”

[lewisl]

Thanks—that’s nice suggestion to add to my suggestion. This would be compatible with making a markdown output as an option instead of the .jl file (which doesn’t have output). I think you understand what I am looking for.

[fonsp]

You are perfectly welcome to fork and to write external scripts! I think it is actually fairly easy to write a small external script to convert Pluto notebooks to .md files, and I can give some pointers if you are interested.

If you want a feature to be implemented in Pluto itself, then that means going through a design process together, and investigating the problem slowly before implementing a solution. If so, I think we should start over.

[lewisl]

It doesn’t feel super cooperative but if you are game I am.

I plan to do a simple Julia function that can be included in a notebook and run when a user likes a state of the notebook to capture. Would love your suggestions: seems like everything is on the cells array, but you wrote Pluto so I’d love your suggestions.

But, I’m all ears/eyes. You seem to lean towards starting from the .jl file, which is the source for the notebook. Please share your thoughts. We have all of Julia at our command...

• Lewis

[colorizer]

How about adding support for Pluto notebook in Weave.jl @fonsp @mpastell? I feel that will be a better implementation given all the features that is being offered right now!

[kjohnsen]

I would actually also like this feature for the purpose of easily publishing a Pluto notebook on my technical blog using a static site generator. Having the file in Markdown would allow the SSG to do the formatting work to be consistent with the rest of the website

[fonsp]

For the purpose of a static website, we think that going through markdown will mean giving up too much markup. Exporting directly to HTML would be ideal, take a look at https://github.com/JuliaPluto/PlutoSliderServer.jl or PlutoStaticHTML.jl (see https://github.com/JuliaPluto/PlutoSliderServer.jl#similaralternative-packages )

[kjohnsen]

It looks like PlutoStaticHTML might work well for my case. Thanks!