GitHub

Pluto.jl notebooks support

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 — Type
struct PlutoDemoCard <: AbstractDemoCard
PlutoDemoCard(path::AbstractString)

Constructs a pluto-format demo card from a pluto notebook path.

Fields

Besides path, this struct has some other fields:

  • path: path to the source markdown file
  • cover: path to the cover image
  • id: cross-reference id
  • title: one-line description of the demo card
  • author: author(s) of this demo.
  • date: the update date of this demo.
  • description: multi-line description of the demo card
  • julia: Julia version compatibility
  • hidden: whether this card is shown in the generated index page

Configuration

You can pass additional information by adding a pluto front-matter section to the notebook. Supported items are:

  • cover: an URL or a relative path to the cover image. If not specified, it will use the first available image link, or all-white image if there's no image links.
  • description: a multi-line description to this file, will be displayed when the demo card is hovered. By default it uses title.
  • id: specify the id tag for cross-references. By default it's infered from the filename, e.g., simple_demo from simple demo.jl.
  • title: one-line description to this file, will be displayed under the cover image. By default, it's the name of the file (without extension).
  • author: author name. If there are multiple authors, split them with semicolon ;.
  • julia: Julia version compatibility. Any string that can be converted to VersionNumber
  • date: any string contents that can be passed to Dates.DateTime. For example, 2020-09-13.
  • hidden: whether this card is shown in the layout of index page. The default value is false.

An example of pluto front matter in the notebook:

#> [frontmatter]
#> title = "passing extra information"
#> cover = "cover.png"
#> id = "non_ambiguious_id"
#> author = "Jane Doe; John Roe"
#> date = "2020-01-31"
#> description = "this demo shows how you can pass extra demo information to DemoCards package. All these are optional."
#> julia: "1.0"
#> hidden: "false"

See also: MarkdownDemoCard, JuliaDemoCard, DemoSection, DemoPage

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

Process the original pluto notebook and saves it.

The processing pipeline is:

  1. preprocess and copy source file
  2. generate markdown file
  3. copy the markdown file to cache folder
  4. insert header and footer to generated markdown file
source