Quarto
A Not So Gentle Introduction

Mickaël CANOUIL, Ph.D.
pro@mickael.canouil.dev

Thursday, the 19th of October, 2023

Quarto

What is Quarto?

https://quarto.org/

What is Quarto?

Quarto (quarto.org):

  • is a free and open-source software, released under the GPL by Posit, PBC.
  • is a command line interface (CLI).
  • mainly supports Python, R, Julia, and Observable JavaScript.
  • supports writing document as Markdown or Jupyter Notebook.
  • can build HTML, PDF, Microsoft Word, etc.
  • can build websites, blogs, books, etc..
  • is built on Pandoc.

What is Pandoc?

Pandoc (pandoc.org):

  • is a free software, released under the GPL by John MacFarlane.
  • is a command line interface (CLI).
  • allows to convert to and between multiple formats.
  • understands Markdown syntax.
  • understands LaTeX math and macros.
  • handles citations and bibliographies.

How does Quarto work? 

%%{
  init: {
    "theme": "dark",
    "themeCSS": ".label foreignObject, .cluster-label foreignObject { font-size: 90%; overflow: visible; }"
  }
}%%
flowchart LR
  A1[qmd] --> C{"knitr<br>(R)"}
  A1[qmd] --> B{"Jupyter<br>(Python)"}
  A2[ipynb] --> B{"Jupyter<br>(Python)"}
  B --> D[md]
  C --> D[md]
  D --> E{Pandoc}
  E --> F[pdf]
  E --> G[docx]
  E --> H[html]
  E --> I[...]

  subgraph engine [Engine]
  B
  C
  end

A Guide to Quarto Versions

timeline
    section Release
      1.0 : July, 2022
      1.1 : August, 2022
      1.2 : November, 2022
      1.3 : April, 2023 : Current
    section Pre-Release
      1.4 : Fall 2023

Getting started

Downloading and installing Quarto

Screenshot of https://quarto.org/docs/download/ webpage

https://quarto.org/

Downloading and installing Quarto

Additionally, you can download and install Quarto using:

Bash
brew install quarto

Screenshot of https://brew.sh/ webpage

PowerShell
choco install quarto

Screenshot of https://community.chocolatey.org/ webpage

Writing with your favourite editor

Screenshot of https://quarto.org/docs/get-started/hello/vscode.html webpage

Screenshot of https://quarto.org/docs/get-started/hello/jupyter.html webpage

Screenshot of https://quarto.org/docs/get-started/hello/rstudio.html webpage

Screenshot of https://quarto.org/docs/get-started/hello/neovim.html webpage

Screenshot of https://quarto.org/docs/get-started/hello/text-editor.html webpage

https://quarto.org/

Quarto: a command line interface

quarto --help

  Usage:   quarto
  Version: 99.9.9

  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               
    create-project  [dir]                 - Create a project for rendering multiple documents  
    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.        
    add             <extension>           - Add an extension to this folder or project         
    install         [target...]           - Installs an extension or global dependency.        
    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.

Checking Quarto is installed

quarto check

Creating a new Quarto project

Bash
quarto create project
 ? Type
 ❯ default
   website
   blog
   manuscript
   book
   confluence

Quarto projects: default

Bash
quarto create project default Default
demo/Default
├── Default.qmd
└── _quarto.yml

1 directory, 2 files

Quarto projects: default

  • _quarto.yml: project configuration file.
Quarto
project:
  title: "Default"
  • Default.qmd: default Quarto document.
Quarto
---
title: "Default"
---

## Quarto

Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see <https://quarto.org>.

Quarto projects: website

Bash
quarto create project website Website
demo/Website
├── _quarto.yml
├── about.qmd
├── index.qmd
└── styles.css

1 directory, 4 files

Quarto projects: blog

Bash
quarto create project blog Blog
demo/Blog
├── _quarto.yml
├── about.qmd
├── index.qmd
├── posts
│   ├── _metadata.yml
│   ├── post-with-code
│   │   ├── image.jpg
│   │   └── index.qmd
│   └── welcome
│       ├── index.qmd
│       └── thumbnail.jpg
├── profile.jpg
└── styles.css

4 directories, 10 files

Quarto projects: book

Bash
quarto create project book Book
demo/Book
├── _quarto.yml
├── cover.png
├── index.qmd
├── intro.qmd
├── references.bib
├── references.qmd
└── summary.qmd

1 directory, 7 files

Quarto projects: manuscript

Bash
quarto create project manuscript Manuscript
demo/Manuscript
├── _quarto.yml
├── index.qmd
└── references.bib

1 directory, 3 files

Quarto features

Writing using the Visual Editor

Screenshot of https://quarto.org/docs/visual-editor/vscode/ webpage

Screenshot of https://quarto.org/docs/visual-editor/ webpage

https://quarto.org/

Mermaid Diagrams

```{mermaid}
flowchart LR
  qmd --> J([Jupyter])
  qmd --> K([knitr])
  J --> md
  K --> md
  md --> P([pandoc])
  P --> pdf
  P --> html
  P --> docx
```
flowchart LR
  qmd --> J([Jupyter])
  qmd --> K([knitr])
  J --> md
  K --> md
  md --> P([pandoc])
  P --> pdf
  P --> html
  P --> docx

Markdown tables

| Default | Left | Right | Center |
|---------|:-----|------:|:------:|
| 12      | 12   |    12 |   12   |
| 123     | 123  |   123 |  123   |
| 1       | 1    |     1 |   1    |

: Demonstration of pipe table syntax
Demonstration of pipe table syntax
Default Left Right Center
12 12 12 12
123 123 123 123
1 1 1 1

Code annotations

  • Source
```r
library(tidyverse)
library(palmerpenguins)
penguins |>                                            # <1>
  mutate(                                              # <2>
    bill_ratio = bill_depth_mm / bill_length_mm,       # <2>
    bill_area  = bill_depth_mm * bill_length_mm        # <2>
  )                                                    # <2>
```
1. Take `penguins`, and then,
2. add new columns for the bill ratio and bill area.

Code annotations

  • Output
library(tidyverse)
library(palmerpenguins)
penguins |>
  mutate(
    bill_ratio = bill_depth_mm / bill_length_mm,
    bill_area  = bill_depth_mm * bill_length_mm
  )
1
Take penguins, and then,
2
add new columns for the bill ratio and bill area.

Cross-references: “figures”

::: {#fig-example}
This is a figure

This is a caption for the figure.
:::

@fig-example is the reference to a figure.
Or is it?

This is a figure

Figure 1: This is a caption for the figure.

Figure 1 is the reference to a figure. Or is it?

Cross-references: “tables”

::: {#tbl-example}
This is a table

This is a caption for the table.
:::

@tbl-example is the reference to a table.
Or is it?
Table 1: This is a caption for the table.

This is a table

Table 1 is the reference to a table. Or is it?

Cross-references: “anything”

Define a new cross-reference type:

crossref:
  custom: 
    - kind: float
      prefix: Text
      name: Text
      ref-type: txt
1
cross-referenceable elements with captions are float.
2
used as the prefix for reference in output (e.g., “In Figure 1, …”).
3
used as the prefix for captions (e.g., “Figure 1: …”).
4
used as the prefix for the reference identifier (e.g., “In @fig-1, …”). 
::: {#txt-example}
This is text

This is a caption for the text.
:::

@txt-example is the reference to a text.

This is text

(a) This is a caption for the text.

Text 1 (a) is the reference to a text.

Cross-reference example 1: The above is a custom cross-reference content.

Shortcodes

{{< meta tittle >}}

Quarto
A Not So Gentle Introduction

{{< iconify exploding-head size=5x >}}

Extensions

Install the quarto-webr extension

Bash
quarto add coatless/quarto-webr
```{webr-r}
fit = lm(mpg ~ am, data = mtcars)
summary(fit)
```

    

  

  

  













Discover more extensions at:







https://quarto-webr.thecoatlessprofessor.com/









Quarto resources




























About














 

















mickael.canouil.fr | License: CC-BY-SA-4.0