Chapter 1: Introduction to Quarto

Quarto is a groundbreaking tool that streamlines the process of converting Jupyter notebooks into various professional formats.

As a creator who works extensively with both R and Python, I've often sought a more polished way to transform my Jupyter notebooks into visually appealing documents. The R ecosystem has long offered this through R Markdown, which I frequently utilize. At times, I would even code my Python projects within an R environment to leverage R Markdown's features.

One persistent challenge I've faced is the aesthetic presentation of Jupyter notebooks, which often lack the options needed for a more 'finished' look. While the interactive programming aspect is certainly beneficial, the overall appearance has fallen short when it comes to sharing work with a broader audience.

The arrival of Quarto changes everything. As a development of R Markdown, Quarto now natively supports Jupyter notebooks. The rendering mechanism remains similar; however, Quarto can utilize both knitr and Jupyter for markdown generation.

With its array of innovative features, you can continue coding in your Jupyter notebooks as usual while incorporating specific instructions to enable rendering in multiple formats such as PDF, HTML, DOCX, Reveal.js, PowerPoint, wikis, websites, and even books. Enhanced commenting provides substantial control over code execution and the arrangement of content, along with improved formatting options for the output.

Moreover, this transformation occurs without disrupting your existing coding workflow, as all Quarto parameters can be seamlessly integrated and ignored during your standard Jupyter lab session.

In this article, I'll guide you through a few foundational examples demonstrating how to render your Jupyter notebooks across various formats. I'll spotlight several features, but to keep it concise, I'll touch on just a few essentials, planning to delve deeper into advanced capabilities in future articles.

Section 1.1: Setting Up Your Notebook for Quarto

To begin, you'll need to install the Quarto command line interface on your machine—detailed instructions can be found here. If you're using VSCode, there’s already a Quarto extension available, and one for PyCharm is likely to follow soon.

Let's consider an existing Jupyter notebook file named my_notebook.ipynb, which contains a simple correlogram.

Next, we’ll prepare this notebook for rendering as a Quarto document. The initial step involves adding a YAML header at the top of the notebook to specify the desired output format. Importantly, this YAML header must be included as a raw block; otherwise, the compiler won't recognize it, which may disrupt your Jupyter session. When included as raw input, it is safely ignored during interactive programming, but it holds significance when Quarto renders the document.

With that, you've created your first basic Quarto document! Let's take a look at some key parameters included in the YAML header:

• title: Sets the document title.
• format: Specifies the output format along with any additional parameters relevant to that format. For instance, specifying HTML output with code folding allows viewers to see code only when they click on the relevant sections—ideal for both technical and non-technical audiences.
• execute: Indicates when code should be executed within the document. By setting enable: true, code will be executed upon each render. This is particularly useful for computationally intensive code that might require significant time to run.
• jupyter: Denotes which language to use for code execution; in this case, it's Python 3, though other engines like Julia can also be configured.

Now, simply enter quarto render my_notebook.ipynb in your terminal, and you'll receive a neatly formatted HTML output with folded code sections for easy viewing.

Section 1.2: Exploring Quarto’s Output Formats

This was a straightforward illustration, and we will explore more complex examples shortly. Quarto supports a variety of output formats. Simply changing html to pdf in the YAML header will yield a clean PDF output, while using docx will generate a Microsoft Word document. Numerous slide presentation outputs, websites, and more are also available. A comprehensive list can be found here. Below is an example of a rendered PDF, complete with an abstract and author details.

Subsection 1.2.1: Utilizing Code Block Parameters for Output Control

One of Quarto's standout features is its ability to manage the display of code and outputs using specialized commenting syntax. In addition to defining global options in your YAML header, you can include YAML parameters within each code block, providing specific instructions on how you want that block to be processed. These commented parameters, which begin with a hash, are ignored during your Jupyter lab session but are meaningful when rendered by Quarto.

For example, I will render my document in Reveal.js format, creating a dynamic slide presentation. I want the code and output displayed side by side in columns on the main slide and will reference my plot accordingly. To achieve this, I will add various parameters to my code block using special comments, followed by a reference to the figure caption in my text.

It's worth noting that the default setting in Reveal.js is not to echo code, so if you wish to display code for a specific block, you'll need to explicitly include echo: true.

The resulting output appears as follows:

In this article, I've merely skimmed the surface of how to utilize Quarto. There are numerous formats and parameters that offer extensive control over the presentation of your data science documents. I plan to post follow-up articles soon to explore more advanced features.

Chapter 2: Video Resources on Quarto

The first video provides an overview of how to publish Jupyter Notebooks using Quarto within RStudio, highlighting key features and best practices.

The second video features Daniel Chen discussing the transition from RMarkdown to Quarto, specifically within Python Jupyter Notebooks, offering insights into the migration process and advantages of using Quarto.