Skip to content

Latest commit

 

History

History
71 lines (51 loc) · 3.91 KB

pluto.md

File metadata and controls

71 lines (51 loc) · 3.91 KB
Raw

[Pluto.jl notebooks support](@id pluto)

Pluto.jl is a modern interactive notebook for Julia. The Pluto notebook content is saved as a Julia script with special syntax decorations to support features like built-in dependency management and reactive cell execution. In this section, we will discuss how we can add demos written using Pluto as DemoCards.

DemoCards.jl natively supports only Julia and markdown files. Pluto notebooks are supported via an extension to the existing package. PlutoStaticHTML.jl is used for rendering pluto notebooks to desired markdown format. The functionality for rendering pluto notebooks is automatically loaded when PlutoStaticHTML is imported into the current environment.

!!! note

Julia versions before julia 1.9 doesn't support the extension functionality.
Requires.jl is used for conditional loading of code in older julia versions.

The set of functionalities supported for Julia and Markdown files is also supported for Pluto. We can compose any number of Pluto, Julia or Markdown files together for a demo.

If one of the demos contains a pluto notebook, we just need to add PlutoStaticHTML to the list of imports.

using Documenter, DemoCards # Load functionality for markdown and julia
using PlutoStaticHTML # Import the pluto notebook functionality to DemoCards

# The tutorials folders/sub-folders can contain pluto, julia and markdown
tutorials, tutorials_cb, tutorial_assets = makedemos("tutorials")

!!! warning

The pluto notebooks in DemoCards are evaluated sequentially and not in parallel.
This was done primarily to avoid repetitive logs in CI.
We recommend using the cache functionality with the pluto notebooks in case of heavy workloads.

Adding frontmatter to pluto notebooks

Pluto.jl has its own GUI to manipulate the front matter of a notebook. This makes it easier for users to create and edit frontmatter. The pluto frontmatter is not saved in YAML format. See this PR for more details.

!!! warning

Frontmatter support for Pluto demoCards are currently limited to the frontmatter support for pluto.
It doesn't support the inference of `title`, `description`, `id` or `cover` from the content of the notebook.
Make sure to explicitly mention custom configs in the frontmatter to avoid surprises.

Cache computationally expensive notebooks

Rendering a Pluto notebook is sometimes time and resource-consuming, especially in a CI environment. Fortunately, PlutoStaticHTML.jl has a cache functionality that uses outputs of previous runs as a cache. If the source pluto notebook (.jl file) or the Julia environment didn't change from the last run, the output md file of the last run is used instead of re-rendering the source. DemoCards stores all the rendered pluto notebooks in a pluto_output folder under the docs folder.

During the demo creation process, DemoCards.jl checks for a file with a cache (filename with .md extension) in docs/pluto_output for each pluto notebook. For example: if the pluto notebook file name is example_demo.jl, it searches for cache with filename example_demo.md. If the cache exists and the input hash and the Julia version matches, rendering is skipped, and the cache is used as output. For more insight into the cache mechanism, visit the cache documentation on PlutoStaticHTML.

Examples

The usage of pluto notebooks as DemoCards can be found in GraphNeuralNetworks.jl.

References

DemoCards.PlutoDemoCard
DemoCards.save_democards(card_dir::AbstractString, card::DemoCards.PlutoDemoCard;
                   project_dir,
                   src,
                   credit,
                   nbviewer_root_url)