Appendix E — Quarto

Published

2025-01-25

Caution

This section is being revised. Thank you for your patience.

Quarto is an ‘open-source scientific and technical publishing system’ that enables users to create dynamic and beautiful documents, reports, presentations, and dashboards.

It is particularly useful for those looking to combine Unix/Linux command line operations with document creation, offering a way to embed executable code within documents. The next sections will guide you through downloading and installing Quarto, .qmd documents, YAML headers and Bash code chunks.

Install

Quarto can be installed from its official website. Follow the platform-specific instructions to install it on your system. Make sure Quarto has been installed correctly and is available in your system’s PATH.

Check if Quarto is in PATH:

quarto --version
## 1.5.28

If the Quarto version isn’t on your PATH, you’ll need to add the location of your quarto installation to PATH. You can do that with the commands below (depending on your shell).

Bash:1

echo 'export PATH="$PATH:/path/to/quarto"' >> ~/.bashrc
source ~/.bashrc

Zsh:2

echo 'export PATH="$PATH:/path/to/quarto"' >> ~/.zshrc
source ~/.zshrc

You can also use which to locate quarto path:

which quarto
## /usr/local/bin/quarto

On macOS, you can use find in the Terminal:

find / -name quarto 2>/dev/null

Development

If you decide to use Quarto documents, you’ll need to decide on the tool (or development environment) you want to use. At the time of this writing, Quarto has tutorials for getting started in RStudio, VS Code, Jupyter, Neovim, or a text editor (like Sublime Text).3 I recommend using an IDE like Visual Studio Code (VS Code) for several reasons:4

IDE Features

VS Code offers typical IDE features (syntax highlighting, code completion, linting, formatting, debugging, etc.) and a Quarto extension. VS Code also has a wide range of extensions for Bash scripting that can significantly streamline development.5

Extensibility

VS Code runs on multiple platforms (Windows, macOS, and Linux), which means you can maintain scripts across different environments using the same tool.

VS Code also supports remote development (i.e., the ability to write and debug scripts running on remote servers and containers from your local machine).

Git Integration

VS Code also has excellent support for version control systems, especially Git.

This integration makes it easier to track changes, revert to previous versions of scripts, and manage updates, all within the same editor environment.

Customization

VS Code can be customized and configured to suit each user’s specific needs, including setting up a personalized development environment with their preferred settings, key bindings, and even look and feel.

Quarto Preview

Quarto documents can be configured to render automatically, which gives users the ability to view document outputs as they’re developed in real-time.

Shell integration

A Terminal window is available in the IDE as a separate window, giving quick access to the command line (with multiple shell options):

Overall, VS Code provides a powerful, versatile, and user-friendly platform to develop, maintain, and manage Shell scripts. There is also a large community around VS Code with lots of tutorials, guides, and forums where users can find support.

Quarto Documents

Quarto documents are a flexible and powerful tool for creating dynamic and reproducible reports, presentations, and publications. Quarto documents can support multiple programming languages, including R, Python, Julia, and Bash. Users can combine narrative text with code in a single document, rendering it into various formats like HTML, PDF, and Word.

This feature proves not only invaluable for data scientists, but for anyone looking to learn a new programming language. Quarto documents are a perfect ‘sandbox’ to experiment with code, take notes, and review the outputs. Moreover, Quarto has the supports cross-referencing, advanced layout options, and beautiful web and book publishing workflows.6

Quarto documents consist of the following elements:

  1. YAML Header: This is used to specify the document’s title, author, and output format.

  2. Narrative Text: Plain language explanations and context.

  3. Code Chunks: Executable code blocks from languages like R, Python, Bash, or Julia.

Additional features include:

  • Results: the output is displayed directly from the executable code chunks (tables, graphs, etc.).

  • Cross-references and Citations: Link to figures, tables, sections, or reference bibliographic sources.

  • Figures and Tables: Markdown syntax can be used to add images and tables.

  • Appendices and Bibliography: Footnotes and references.

Literate programming is a programming paradigm that intertwines code with human-readable narrative, allowing programmers to write programs in the order best suited for human understanding. Donald Knuth developed this approach to make code more understandable and maintainable.

‘Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.’ - Donald Knuth. Literate Programming (1984) in Literate Programming. CSLI, 1992, pg. 99.

Literate programming can foster clearer communication of complex programming concepts and enhances collaboration among developers.

YAML header

YAML is a lightweight markup language that’s easy to write and read. In Quarto, the YAML header is used to configure document properties such as the title, engine, output format, and more. It serves as the foundation for controlling how your Quarto document behaves and appears.

Quarto documents are written in markdown and can include executable code in various programming languages, including Unix commands. The YAML header is placed between three dashes --- at the top of each Quarto document to specify metadata and global options.

---
title: "Using Bash"
---

To run Bash commands, specify knitr in the engine field of in the YAML header of the Quarto file, and any additional key-value pairs:7

---
title: "Using Bash"
engine: knitr
knitr:
  opts_chunk: 
    collapse: true
---

Code Chunks

One of the powerful features of Quarto is the ability to integrate executable code chunks into Markdown documents. You can create bash code chunks using the following syntax:

```{bash}
echo "foo" 
```

Bash code chunks allow you to include executable commands within your Quarto documents. You can also specify the code chunk options with the hash-pipe (#|):8

```{bash}
#| code-fold: show
#| code-summary: 'show/hide echo'
echo "foo" 
```

When the document is rendered, the narrative text is included with the output from the commnads.

show/hide echo 
echo "foo"
## foo

This simplicity allows authors to focus on their content rather than formatting.

Code Chunk Isolation

When incorporating Bash code chunks into Quarto documents, an essential detail to remember is the behavior of the working directory during file rendering. By default, Quarto sets the working directory to the location of the current document within the project.

Consider the following scenario in a Quarto project:

# This code chunk displays the current working directory
pwd
## /Users/mjfrigaard/projects/books/fm-unix

Although we can navigate to a different directory within a given code chunk:

cd data # Change the current working directory to 'data' 
pwd # confirm the change
## /Users/mjfrigaard/projects/books/fm-unix/data

It’s crucial to note that Quarto resets the working directory to the document’s location for each new code chunk:

# Verifying the working directory, which reverts to 
pwd # the document's location for each new code chunk
## /Users/mjfrigaard/projects/books/fm-unix

This behavior is different than what we’d see in Posit Workbench’s Terminal on my local machine:

  1. The current working directory is ~/projects/books/fm-unix/ (as indicated by the Terminal prompt):

fm-unix/ directory
  1. If we change the working directory with .., we are in the books/ directory (as indicated by the books in the Shell window):

books/ directory
  1. When we check the current working directory again with pwd, we see the location is still ~/projects/books/.

Still in the books/ directory

This difference in behavior can be frustrating, but it also means we’ll start with a ‘clean slate’ in each new code chunk!

Recap

This chapter covered a guide on how to use Quarto for embedding and executing Bash code, a powerful feature for Unix/Linux users and developers who need to document and automate command line tasks.

  • Setting Up Quarto: We covered the resources and prerequisites for installing Quarto, and how to use Quarto within Visual Studio Code (VS Code). We included setting VS Code with the Quarto extension, and options for configuring the IDE.

  • Writing and Executing Bash Code: We discussed setting up Bash in Quarto documents, including how to configure the YAML header in the Quarto document to include Bash as the programming language, and ensuring Quarto documents can recognize and execute Bash code.

VS Code and Quarto are powerful tools. The IDE provides a user-friendly interface, extensive plugin ecosystem, and strong support for Quarto’s interactive capabilities.

See a typo, error, or something missing?

Please open an issue on GitHub.

  1. Bash is common in Linux and older macOS versions↩︎

  2. Zsh is now the default in shell in macOS↩︎

  3. For what its worth, I’ve been using RStudio for years and love it. However, I’ve also used Quarto in VS Code and love many of it’s features.↩︎

  4. If you prefer a ‘Free/Libre Open Source Software Binary of VS Code’, check out vscodium↩︎

  5. Bash Debug and Bash IDE are VS Code extensions specifically designed for Bash scripting, which we’ll cover in a later chapter.↩︎

  6. In fact, this entire book was written using Quarto documents.↩︎

  7. Read more about configuring shell code blocks in Quarto in the documentation.↩︎

  8. Consult the full list of code chunk options in the Quarto documentation.↩︎