A Not So Gentle Introduction

pro@mickael.canouil.dev

Thursday, the 19^th of October, 2023

Getting started

Downloading and installing Quarto

Additionally, you can download and install Quarto using:

Homebrew (macOS/linux)

Bash

brew install quarto

Chocolatey (Windows)

PowerShell

choco install quarto

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

Video Player is loading.

Current Time 0:00

Duration -:-

Loaded: 0%

Stream Type LIVE

Remaining Time -:-

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

Mermaid Diagrams

```{mermaid}
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 >}}

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/

A Not So Gentle Introduction Mickaël CANOUIL, Ph.D. pro@mickael.canouil.dev Thursday, the 19 th of October, 2023

A Not So Gentle Introduction
Slide 2
What is Quarto?
What is Quarto?
What is Pandoc?
How does Quarto work?
A Guide to Quarto Versions
Getting started
Downloading and installing Quarto
Downloading and installing Quarto
Writing with your favourite editor
Quarto: a command line interface
Checking Quarto is installed
Creating a new Quarto project
Quarto projects: default
Quarto projects: default
Quarto projects: website
Quarto projects: blog
Quarto projects: book
Quarto projects: manuscript
Quarto features
Writing using the Visual Editor
Mermaid Diagrams
Markdown tables
Code annotations
Code annotations
Cross-references: “figures”
Cross-references: “tables”
Cross-references: “anything”
Shortcodes
Extensions
Quarto resources
About