Possible feature: integrate Pluto pages.

[lmiq]

I'm fantasizing about the possibility of integrating Pluto pages with Documenter.

The idea would be that a menu entry of a Documenter page displayed in the content tab the static html of a Pluto notebook.

The degree of integration could vary:

• can the style of the notebook follow that of the Documenter pages?
• can the title itens of the notebook be used to populate sub menu itens of the docs, like in a regular doc page?
• can be the notebook be run as part of doc tests?

The utility of this in creating example pages and tutorials would be enormous.

[gdalle]

I would also find it very cool!
A few remarks:

• @adrhill has achieved something similar in his "Julia for ML" course, not sure how: https://adrianhill.de/julia-ml-course/
• @rikhuijzer also has a related toolbox with https://github.com/rikhuijzer/JuliaTutorialsTemplate

[lmiq]

https://github.com/rikhuijzer/JuliaTutorialsTemplate

Something like that is exactly what I was thinking, except integrated to Documenter.

It may be that a function that converts a Pluto notebook in a regular markdown (Pluto has one?), then used within the make.jl can handle that.

[lmiq]

Related: fonsp/PlutoUtils.jl#6

[odow]

except integrated to Documenter.

It may be that a function that converts a Pluto notebook in a regular markdown (Pluto has one?), then used within the make.jl can handle that.

I don't think that documenter is the place to add extensions like this. Documenter accepts Markdown. It is the responsibility of other packages to prepare that Markdown. This is what Literate.jl and Weave.jl do. It has been working well, so I don't think we need something special for Pluto.

Related: #1129

[lmiq]

Yes, I think it is fair that a package external to Documenter should create the markdown.

But what about linking raw html pages, as a complete html generated by Pluto?

(What makes Pluto special here is how popular it is, to be honest. Maybe there's nothing to to on this side, but we should think about the possibilities)

[odow]

But what about linking raw html pages, as a complete html generated by Pluto?

As a complete raw page? You can currently link to an HTML page.

You can also use the @raw html block: https://documenter.juliadocs.org/stable/man/syntax/#@raw-format-block

In SDDP.jl (code, web), I do:

```@raw html
<embed type="text/html" src="../../assets/value_function.html" width="100%">
```

There is an open issue for links in the sidebar: #344

[lmiq]

(Edit) That works, but needs some work:  The height of the page needs to be tuned. I'll see if I get that right.

[lucaferranti]

The discussion here might also have some relevant tips: fonsp/Pluto.jl#1345 (reply in thread) iirc, they do mention a javascript library to adjust the height of the iframe

[rikhuijzer]

This is supported by PlutoStaticHTML.jl: https://plutostatichtml.huijzer.xyz/stable/#Documenter.jl

This page for example is a Pluto notebook: https://sirus.jl.huijzer.xyz/dev/binary-classification/. You can click on the “view source” button on that page to see the Pluto notebook.

[adrhill]

@adrhill has achieved something similar in his "Julia for ML" course, not sure how: https://adrianhill.de/julia-ml-course/

I used PlutoSliderServer in combination with iframes:

Using PlutoSliderServer.jl, notebooks are automatically exported to HTML using GitHub Actions. The website is built using Franklin.jl and currently uses iframes to include the Pluto notebooks. To make this look more seamless, the website re-uses a lot of Pluto’s CSS. Most of the magic then happens in this GitHub Action for deployment.

Let me know if you have any further questions!

[lmiq]

This is supported by PlutoStaticHTML.jl: https://plutostatichtml.huijzer.xyz/stable/#Documenter.jl

This page for example is a Pluto notebook: https://sirus.jl.huijzer.xyz/dev/binary-classification/. You can click on the “view source” button on that page to see the Pluto notebook.

Oh, that's nice, definitely that is what I was searching for.

I tried to use it now and had some issues, but I'll post them there.

I'll close the issue here.