Using Quarto

Quarto is a system for publishing technical content. We’ll use with source files written in the Quarto flavor of Markdown, which can include mathematical notation using LaTeX syntax and code chunks that are evaluated during the publishing process. One then “renders” the source file into either HTML or PDF.

Installing and using Quarto

Unless you plan to generate your problem set solutions on the SCF, you’ll need to install Quarto.

Once installed, you should be able to run commands such as quarto render FILE and quarto preview FILE from the command line.

To render to PDF, you’ll need a LaTeX engine installed. A good minimal solution if don’t already have LaTeX installed (e.g., via MicTeX in Windows or MacTeX on MacOS) is to install tinytex: quarto install tinytex.

Quarto also runs from the Windows Command shell or PowerShell.

quarto convert converts back and forth between the Jupyter notebook (.ipynb) and Quarto Markdown (.qmd) formats. So if you prefer, you can develop in a notebook and then convert to qmd and then render to prepare a nice-looking PDF for problem set/project/presentation submission.

The Quarto manual has more details on using Quarto specifically in the context of using Julia.

Example Quarto document

Here’s example content of a Quarto document. The first part is the YAML header/metadata giving details of how the document should be processed.

---
title: "Problem Set 1 Solutions"
author: "Chris Paciorek"
date: "2025-01-21"
engine: jupyter
---

Here's some math: $\int \pi(\theta)d\theta = 1$.

Here's a code chunk that is evaluated.

```{julia}
x = 3;
println("The result is $(x*7).")
```

More details are available in the Quarto manual, including options for controlling the output from code chunks.

Rendering engines

By default, Quarto uses Jupyter to process code chunks. (Note that engine: jupyter is specified above in the metadata but is not needed.)

There are other rendering engines one can use to process the code chunks, with various advantages and disadvantages.

Jupyter engine

The Jupyter engine requires that the IJulia kernel installed – see the howto on accessing Julia.

To use a specific kernel, you can replace engine: jupyter with jupyter: <kernelname>, where <kernelname> is the name of the Jupyter kernel to be used. On the SCF, this could be jupyter: julia-1.10 as there is a kernel named julia-1.10.

Some downsides of this engine are:

  • All output from a chunk is printed after the chunk rather than immediately after the line of code causing the output.
  • Only the output from the last line of code in a chunk is printed out (except if print() is used explicitly).

Julia engine

There is also now a Julia engine for Quarto. To use it, simply have engine: julia in the metadata.

The rendering uses the QuartoNotebookRunner.jl package. It will supposedly install it in an isolated way, and that worked on my laptop, but I had package version incompatibilities on the SCF.

Some downsides of this engine, as with the Jupyter engine, are:

  • All output from a chunk is printed after the chunk rather than immediately after the line of code causing the output.
  • Only the output from the last line of code in a chunk is printed out (except if print() is used explicitly).

Knitr engine (via R)

The knitr engine requires that you have R installed on your computer, with the rmarkdown R package installed.

To use it, simply have engine: knitr in the metadata.

Some upsides of this engine involve having the output from the code chunks print out nicely:

  • Output from a chunk is interspersed with the line of code creating the output.
  • Output from all lines is printed out.

However, I have had some difficulties with the knitr engine, including

  • Errors when trying to have plots included in the output.
  • Having output from simply invoking an object name (e.g., x rather than print(x)) sometimes appear in the terminal/console rather than in the rendered document.
  • The #| error: true chunk execution option does not seem to work (I’ve filed a bug report about this.).