Quarto Integration

Introduction

By combining Julia and Quarto, you can create interactive, visually appealing, and data-driven documents. Quarto enables the user to prepare fully reproducible files containing all the interactive components in just one main file.

In this tutorial, we will guide you through Quarto integration with Julia. More specifically, the instructions below refer to the Julia IDE that can be launched via JuliaHub. We also discuss various preview and rendering options.

Check out this video to see how easy it is to use Quarto with Julia:

NOTE: In case you are experiencing problems with rendering in the IDE, use this simple workaround:

bash $ rm -rf ~/data/.julia/conda $ julia -q julia> using Pkg; Pkg.add("IJulia"); using IJulia; notebook(); exit() $ export QUARTO_PYTHON=/home/jrun/data/.julia/conda/3/x86_64/bin/python3 $ quarto render test.qmd

Installing Quarto

The first step is to ensure that Quarto is installed. In this guide, we show how to use the Quarto extension from VS Code. You can either perform this step locally or via the Julia IDE on JuliaHub.

To install the Quarto extension, simply navigate to VS Code extension manager and type quarto. Use the internal instructions for completing the setup.

For more installation options, visit the Quarto documentation at https://quarto.org/docs/getting-started/installation.

Setup

Preparing a Quarto Project

The Quarto project directory should contain the main file in the .qmd format plus additional files in the form of images or other data.

If you are still working on the contents, consider turning on contextual assistance by executing the command Quarto: Show Assist Panel in the panel.

Embedding Julia Code

Quarto supports markdown, so Julia code blocks can be included in the Quarto file both as inline and as independent blocks. The latter should be surrounded by triple backticks with julia in the first line. The example below illustrates this convention:

```julia
# your Julia code goes here
```

Note that if you add braces around the first word ({julia}), the code block will become executable during the rendering step.

By default, saving a Quarto file doesn't trigger rendering but this behavior can be modified. Just type quarto.render in the settings and follow the internal instructions there. Be aware that rendering on saving might slow down the preview considerably due to longer computation time.

Inline code should be surrounded by backticks with julia appearing as the first word, like so: $`julia`$.

Alternatively, you could also explore the ready options for code embedding by typing the command Insert Snippet in the panel.

Adding Julia Packages

Julia packages can be used in Quarto documents. Any dependencies required by your code should be installed via a package manager - in this case, we recommend using the standard package manager Pkg.jl.

For instance, if you wish to add the Plots package to, you should include the following commands at the beginning of the code block:

using Pkg
Pkg.add("Plots")

Note that it's preferable to manage dependencies using a .toml file (especially if your project uses several packages). By using a project file, you also make sure that the Quarto document is reproducible and easier to use in the future.

Quarto Output

Quarto is able to generate output in many popular formats, including PDF and HTML. More advanced output settings can be manipulated using the configuration file (quarto.yaml).

For more details on output customization, refer to the Quarto documentation: https://quarto.org/docs/computations/julia.html.

Preview

In order to use Quarto's handy live preview feature, type the following commands and specify the desired preview options:

# HTML preview
quarto preview example.qmd

# PDF preview
quarto preview example.qmd --to pdf

# Jupyter notebook preview
quarto preview notebook.ipynb

As with rendering (see below), Quarto does not execute notebook cells by default. This can be done in the editing step or, if you prefer, directly in the preview command, like so:

quarto render notebook.ipynb --execute

This behavior can also be specified in the notebook's YAML file:

---
title: "Example Notebook"
execute:
  enabled: true
---

Rendering

Computations within executable code blocks are performed automatically. Rendering to all formats is done by typing:

quarto render example.qmd

To select specific output formats, use the following commands:

quarto render document.qmd --to pdf
quarto render document.qmd --to docx

Rendering a Jupyter notebook is done in a similar way:

quarto render notebook.ipynb

By default, Quarto will not execute all cells. This can be either done when editing the notebook or, if you wish to do it in the rendering step, by typing:

quarto render notebook.ipynb --execute

Additional formatting

The user also has direct control over plotting settings and formatting functionality, such as specifying a table of contents and numbering conventions. For instance, by adding the snippet bellow to the YAML file (the one with .qmd extension), you can set default width and height of some high-resolution figures and adapt them to a Retina display:

---
fig-width: 6
fig-height: 4
fig-retina: 2
---

Similarly, if you wish to add the table of contents and control its numbering, you can use the following code:

---
toc: true
number-sections: true
---

Webinar from 2022

Learn more by watching the webinar by J.J. Allaire.