Quarto Extensions

for the Julia Community

Patrick Altmeyer
Ronny Bergmann

Friday, July 12, 2024

Overview

  1. What is Quarto?
  2. Julia-themed Quarto: Simple Extensions
  3. Quarto for Documentation
  4. Quarto for JuliaCon Proceedings

What is Quarto?

  • Cross-platform open-source scientific publishing tool with a focus on reproducibility.
  • Based on Markdown, which is easy to learn and write.
  • Very flexible and can be extended with custom templates and styles.
---
title: "Hello Quarto"
jupyter: julia-1.10
---

## Hello Quarto!

Blending Markdown and 
Julia code:

```{julia}
#| echo: true

println("Hello, Quarto!")
```

Julia-themed Quarto

Simple Quarto extension that adds a Julia-themed touch to your documents.

Extensions are a powerful way to modify and extend the behavior of Quarto.

Getting Started

To install the Julia-themed Quarto extensions, run:

quarto add pat-alt/quarto-julia

Usage

Simply adjust the Quarto header of your document:

---
title: Julia-themed Quarto
format:
  julia-html: default
  julia-revealjs:
    scrollable: true
author: pat-alt
date: last-modified
---

Available Formats

  • HTML (articles)
  • Revealjs (presentations)

Preview and Render

quarto preview yourdoc.qmd
quarto render yourdoc.qmd

Fonts

  1. JuliaMono font for monospace text and code.
  2. Barlow font for headers and blockquotes (thanks @cormullion).
  3. Roboto font for everything else.
  4. Also available is Bangla MN by Muthu Nedumaran of Murasu Systems, which is closely related to the official Julia logo font.

Code

Inline code looks like this print("hello 🌍"). Code blocks look like this (Revealjs not affected):

using CounterfactualExplanations, TaijaData

# Data and Classifier:
counterfactual_data = CounterfactualData(load_linearly_separable()...)
M = fit_model(counterfactual_data, :Linear)

# Select random sample:
target = 2
factual = 1
chosen = rand(findall(predict_label(M, counterfactual_data) .== factual))
x = select_factual(counterfactual_data, chosen)

# Counterfactual search:
generator = GenericGenerator()
ce = generate_counterfactual(x, target, counterfactual_data, M, generator)

Callouts

Note

This is a note in julia_blue. Icons are deactivated in Revealjs.

Tip

This is a tip in julia_green.

Caution

This is a caution callout in julia_purple.

Warning

This is a warning in julia_purple.

Important

This is an important callout in julia_red.

Documentation

Write tutorials in Quarto that fully integrate into the rendered documenation.

Manopt.jl

Goals

Tutorials that are

  • integrated in the documentation (Documenter.jl)
    • Integrated Links within the documentation
    • include mathematical formulae
  • render into Markdown
  • show code and results
  • reproducible
  • run on CI (cached)

General Workflow

  1. write tutorials (.qmd) for a package in tutorials/
  2. run their code when generating the documentation
  3. render them (as .md) into docs/src/tutorials/
---
title: "A short example"
---

```{julia}
#| echo: false
#| output: false
cd(@__DIR__); # activate env.
using Pkg; Pkg.activate(".");
```

Let's start with loading
necessary packages

```{julia}
using Manopt, Manifolds
M = Sphere(2)
```

and then we continue with [...]

Workflow II: Configure Quarto

_quarto.yml in tutorials/:

  • one file:
    quarto render file.qmd
  • quarto render in tutorials/ renders all but !
  • cached in tutorials/_freeze
project:
  title: "My Tutorials"
  output-dir: ../docs/src/tutorials
  render: # specify some
    - "*.qmd"
    - "!NotThisFile.qmd"

format: #render to md
  commonmark:
    variant: -tex_math_dollars
    wrap: preserve

Tip. Use the
Quarto VS Code extension
and the command
Quarto Preview

Workflow III: Documenter

  • Use CondaPkg.jl to handle/install Python, creating a CondaPkg.toml specifying the Python version
[deps]
jupyter = ""
python = "3.11"

And include rendering the tutorials in your make.jl

using CondaPkg
CondaPkg.withenv() do
    tutorials_folder = (@__DIR__) * "/../tutorials"
    run(`quarto render $(tutorials_folder)`)
end

Workflow IV: GitHub Action

On CI: Set up caches:

- name: Cache Quarto
  uses: actions/cache@v4
  with:
    path: tutorials/_freeze # Quarto Cache
    key: ${{ runner.os }}-${{ env.cache-name }}-${{ hashFiles('tutorials/*.qmd') }}
    restore-keys: |
      ${{ runner.os }}-${{ env.cache-name }}-
- name: Cache Documenter
  uses: actions/cache@v4
  with:
    path: docs/src/tutorials # Cache rendered tutorials
    key: ${{ runner.os }}-${{ env.cache-name }}-${{ hashFiles('tutorials/*.qmd') }}
    restore-keys: |
      ${{ runner.os }}-${{ env.cache-name }}-

There we are!

Cached, reproducible tutorials within Documenter.jl.

Challenges

  • Cache vs. breaking versions of the package

  • Recommendation: Maybe print package versions

  • Quarto replaces spaces in markdown links
    [A](@ref B) with [A](@ref%20B).

    These have to be “escaped”:
    `[A](@ref B)`{=commonmark}

  • Due to pandoc:
    for now write math in $...$ and not ``...``

Documenter Summary

Outlook / Soon

JuliaCon Proceedings

The quarto-juliacon-proceedings extension adds support for writing a JuliaCon Proceedings article in Quarto.

Getting Started

To install the JuliaCon Proceedings extension, run:

quarto add pat-alt/quarto-juliacon-proceedings

Disclaimer

PDF version resembles the official JuliaCon Proceedings format almost exactly but it is not officially endorsed by the JuliaCon Proceedings team.

See this issue.

Supports both PDF and HTML:

---
title: JuliaCon Proceedings in Quarto
format:
  juliacon-proceedings-pdf:
    keep-tex: true
  juliacon-proceedings-html: default
author:
  - name: Patrick Altmeyer
    affiliations:
      - Delft University of Technology
    orcid: 0000-0003-4726-8613
---

Motivation

JuliaCon Proceedings to set an example for reproducibility:

  • Code, results and text in one document.
  • Executable code blocks serve as a form of testing.
  • Same document can be rendered into HTML, PDF, …

Benefits for the authors:

  • Essentially zero maintenance for the authors.
  • LaTeX option still available for those who prefer it.

Showcase

The following two example articles were rendered using the extension:

  • Official extension template: [pdf, html]
  • Altmeyer, Deursen, et al. (2023): [pdf, html]

Comparison

Proposed Version

Published Version

More Information