blog/posts/tips-and-tricks-for-using-quarto-with-julia/

[utterances-bot]

Patrick Altmeyer - A year of using Quarto with Julia

A short companion post to my presentation on using Quarto with Julia at the 2nd JuliaLang Eindhoven meetup in November, 2022.

https://www.paltmeyer.com/blog/posts/tips-and-tricks-for-using-quarto-with-julia/

[pat-alt]

This working?

[floswald]

hey! great post, thanks. exactly what I was looking for - that thing with the environment in the first chunk is nowhere documented. so - in global env you need at least IJulia to run this, right? thanks

[pat-alt]

hey! great post, thanks. exactly what I was looking for - that thing with the environment in the first chunk is nowhere documented. so - in global env you need at least IJulia to run this, right? thanks

Exactly, IJulia is always required.

[kellertuer]

Hi Pat. I moved my Manopt.jl tutorials to Quarto and by now that is working quite will, just that I am still checking in (committing) the locally rendered md files into the repo. Do you know an example where (e.g. before running Documenter.jl) Quarto is run on CI?

[pat-alt]

Hi Ronny, afraid I haven't seen examples of that and haven't tried to do it myself. But the extra rendering step is starting to get a bit tedious, so this would indeed be quite useful. I've been very busy with other stuff recently, but should have time to look at a better setup for Quarto over the summer. Relatedly, there is also some interesting stuff happening over at Literate.jl.

ccing one of my collaborators who just asked me about this yesterday @laurikskl

[kellertuer]

Hi, I got some hints on Slack today and will work on that this week, maybe we have a public working example somewhen soon :)

and – nice, a mix of Literate and quarto seems also very nice. I actually did my very first tutorials with Literate but felt Pluto was better fitting for some time, before now coming to Quarto.

[kellertuer]

Here is a first variant on this PR that does the job, and I even can explain why and how https://github.com/JuliaManifolds/Manopt.jl/pull/254

Might still need a bit of polishing to get a few caches setup for speedup and to avoid re-rendering too often. It is also only mildly complicated. From make.jl it installs python/jupyter with conda, (CondaPkg.jl) to then issue the quarto call, which runs python within Julia to run Jupyter to again run the cells in Julia. It uses 2 environments, one for the docs (with CondaPkg and IJulia) and one for the quarto notebooks themselves.

edit: This might have two limitations for now: (a) I have one tutorial that uses asymptote for rendering, which I could not get to work on CI and (b) I have one notebook that does a benchmark (30 seconds on my Apple M1) which I canceled after one hour on CI. Those are still committed and excluded from automatic run. Besides that 4 caches (Julia, CondaPkg, Quarto _freeze and for the rendered results) speed up the CI quite a bit. I will think about a post about this once I find a nice place to do so.

[kellertuer]

One further remark, for me, your admonition-trick did not work (the spaces get converted to other spaces). But I found something else, that even makes it possible to keep [`MyType`](@ref) things, since a link with @ might be seen as a citation by quarto and spaces in the link are converted into %20. To avoid that, one can declare inline code or code blocks to be {=commonmark} then they are kept unchanged.

Examples

• ``[`MyType`](@ref MyPackage.MyType)``{=commonmark} (or when referencing a header in Documenter
• For blocks

  ```{=commonmark}
  !!! note "Even titles do not have to be escaped!"
  Your Note

  
  Just if someone struggles with the different things Quarto/Pandoc and Documenter want to Markdown with