Introduction to Quarto

What is Quarto

The Quarto CLI

0. In order to use Quarto you need to install Quarto first. The easiest way is to get the package for your desired platform directly from https://quarto.org/docs/get-started/. If you need the most recent version you can also get the source code from the quarto-cli git repository.

1. After Quarto is installed on your system you can get an overview of all subcommonds when you type quarto help (followed by pressing ENTER) in a terminal:

  Usage:   quarto 
  Version: 1.4.553

  Description:

    Quarto CLI

  Options:

    -h, --help     - Show this help.                            
    -V, --version  - Show the version number for this program.  

  Commands:

    render     [input] [args...]     - Render files or projects to various document types.
    preview    [file] [args...]      - Render and preview a document or website project.  
    serve      [input]               - Serve a Shiny interactive document.                
    create     [type] [commands...]  - Create a Quarto project or extension               
    use        <type> [target]       - Automate document or project setup tasks.          
    add        <extension>           - Add an extension to this folder or project         
    update     [target...]           - Updates an extension or global dependency.         
    remove     [target...]           - Removes an extension.                              
    convert    <input>               - Convert documents to alternate representations.    
    pandoc     [args...]             - Run the version of Pandoc embedded within Quarto.  
    typst      [args...]             - Run the version of Typst embedded within Quarto.   
    run        [script] [args...]    - Run a TypeScript, R, Python, or Lua script.        
    install    [target...]           - Installs a global dependency (TinyTex or Chromium).
    uninstall  [tool]                - Removes an extension.                              
    tools                            - Display the status of Quarto installed dependencies
    publish    [provider] [path]     - Publish a document or project to a provider.       
    check      [target]              - Verify correct functioning of Quarto installation. 
    help       [command]             - Show this help or the help of a sub-command.       

There are many Quarto subcommands available. You can get more details about each subcommand when you type quarto <SUBCOMMAND> help in the terminal: e.g. quarto render help provides detailed information about rendering files or projects to various document types - including some usage examples at the end.

Authoring

Render vs preview

The quarto render and quarto preview commands are used to generate output from a Quarto (.qmd) document.

The quarto render command generates output in all formats specified in your YAML header (e.g., pdf, html, word) or in your command line with the option --to, while the quarto preview command only generates output in a format suitable for viewing in a web browser.

In a typical workflow, you would use the quarto preview command to view the output of your document as you are working on it.

quarto preview my.qmd

This command will start a local web server and open a web browser to view the output of the document. The web server will automatically update the output as you make changes to the document.

Once you are ready to produce your final output you can use the quarto render command.

quarto render my.qmd

Computations

Quarto lets you perform computations within your notebook. This is typically done using code blocks denoted by three backticks followed by the language you’re using in curly brackets.

```{python}
1 + 1
```

Quarto supports computations in several languages:

• Python
• R
• Julia
• Observable

Additional languages can also be supported through other Jupyter kernels (see Engines below). See this page for a list of Jupyter kernels.

The languages and packages used in your computations must be available in your render environment, and are often installed through other means, for example using conda or a container platform.

Loaded packages and variables defined within a code block are also accessible from other code blocks, including inline code blocks. For example, here we create a figure within a div (:::) and reference the x variable in both the figure caption and text body.

:::{#fig-plot-alt}

```{r}
x <- 1:10
y <- x^2

plot(x, y)
```

A plot of $x$ against it's square (n = `{r} length(x)`).
:::

This paragraph refers to @fig-plot-alt for a plot of $y=x^2$ 
based on `{r} length(x)` points.

The output of computations can be controlled using execution options. These can be set for the whole document in the yaml front-matter at the top of the document, e.g.,

---
title: My Experiment
execute:
  echo: false
---

Alternatively, execution options can be specified within each code block, e.g.,

```{python}
#| echo: false
#| output: asis
print("""
## Introduction

This is Markdown text.
""")
```

Computations can also be used to dynamically generate Markdown or HTML content by using the output format asis. For example, document sections can be dynamically generated from an input file.

Document types

Quarto can generate a number of document output types, including PDF, HTML, and MS Word. The output format can be set on the command line via the --to option, or by setting the format option in the yaml configuration. For instance, the following header configuration will generate PDF output:

---
format: pdf
---

Presentation

In addition to regular document formats, there is support for formats that will generate presentations, including revealjs (HTML), pptx (PowerPoint) and beamer (LaTeX/PDF).