Quarto markdown

EVR 628- Intro to Environmental Data Science

Juan Carlos Villaseñor-Derbez (JC)

Rosenstiel School of Marine, Atmospheric, and Earth Science and Institute for Data Science and Computing

Quarto markdown

Quarto markdown

• Allows you to build documents
  • slides
  • html files
  • pdfs
  • word documents
  • books…
• Particularly useful if your document heavily depends on R-generated content

Source: quarto.org

Quarto markdown

• Some people use them throughout their analysis
  • Pros:
    • You can write tons and tons of explanations as to why you are doing something
    • You can include equations
  • Cons:
    • You have to run the entire document, from top to bottom, every time you want to update it
    • Sometimes more is not better

Quarto markdown

• We’ll build a presentation
• Then a document (html and pdf)
• Finally, a website

Parts of a Quarto file

What to produce + content (markdown and/or R)

YAML header

• At the top of your file, you will see something like this:

---
title: "This is my title"
subtitle: "And I can add a subtitle"
author: "Jon Doe"
institute: "University of whatever"
format: html
---

• This section is called the YAML header.
• It uses key-value pairs (e.g. key: value is name: "JC")
• Key-value pairs dictate type of document and “options” (style, themes, output)
• Different types of documents allow for different YAML fields
  • Revealjs slides
  • HTML
  • PDF

Content: Headings

Markdown Syntax	Output
# Heading 1	Heading 1
## Heading 2	Heading 2
### Heading 3	Heading 3
#### Heading 4	Heading 4
##### Heading 5	Heading 5
###### Heading 6	Heading 6

Content: Text

Formatting text is easy:

• We use asterisks “*” to mark text as
  • *italics*, **bold**, ***bold italics*** become
  • italics, bold, bold italics
• Use “^” and “~” to make superscripts and subscripts
  • 20^th^ century / CO~2~ become
  • 20^th century / CO₂

Content: Links and images

• You can include URL links:
  • Use <https://jcvdav.github.io/EVR_628/> to produce
  • https://jcvdav.github.io/EVR_628/
• You can link text:
  • I can write Click [here](https://jcvdav.github.io/EVR_628/) and get
  • Click here
• You can link to an image:
  • ![Caption (optional)](img/RStudio.png)

Caption (optional)

Content: Lists

Markdown Syntax	Output
* unordered list + sub-item 1 + sub-item 2 - sub-sub-item 1	unordered list sub-item 1 sub-item 2 sub-sub-item 1
1. ordered list 2. item 2 i) sub-item 1 A. sub-sub-item 1	ordered list item 2 sub-item 1 sub-sub-item 1

Content: Tables

You can build tables by hand

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

Right	Left	Default	Center
12	12	12	12
123	123	123	123
1	1	1	1

• The location of the : defines alignment of the cell contents
• Although I prefer building them with code

Content: Equations are easy to include

You use single dollar signs to have “inline” math:

• Pythagoras's theorem is $a^2 + b^2 = c^2$
• Pythagoras’s theorem is \(a^2 + b^2 = c^2\)

Or double dollar signs to have “display” math:

$$x = -b \pm \frac{\sqrt{(b^2 - 4ac)}}{2a}$$

renders as

\[x = -b \pm \frac{\sqrt{(b^2 - 4ac)}}{2a}\]

Content: Others

Full documentation here shows how to include:

• videos
• diagrams
• callout blocks
• Dividiers…

Content: Content produced by code

You can embed R code that produces content in your Quarto file using code chunks:

```r
# Load packages
library(EVR628tools)
library(tidyverse)
library(knitr)
# Load data
data("data_milton")
# What am I doing here?
max_wind <- data_milton |> 
  mutate(date = date(iso_time)) |> 
  group_by(date) |> 
  summarize(max_wind = max(wind_speed))
# Build a table
kable(x = max_wind,
      col.names = c("Date", "Max. wind speed (kts)"),
      align = "ll")
```

Date	Max. wind speed (kts)
2024-10-04	30
2024-10-05	35
2024-10-06	73
2024-10-07	155
2024-10-08	145
2024-10-09	140
2024-10-10	105
2024-10-11	60

Content: Content produced by code

It also works for figures:

```r
ggplot(data = max_wind,
       aes(x = date, y = max_wind)) + 
  geom_line() +
  geom_point(size = 3) +
  theme_bw() +
  labs(x = "Date",
       y = "Max. wind speed (kts)")
```

Let’s build some slides

Let’s build a sebsite

1) Building a website with Quarto

1. Project -> New project -> New Directory -> Quarto Website
2. Give it a name. Perhaps call it my_site or website or something like that.
3. Check “Create a git repository” and uncheck “Visual editor”
4. Click create
5. All the project files will be available
6. Modify the _quarto.yml file so that the first three lines look like this:

project:
  type: website
  output-dir: docs # You will need to add this line

7. Go to your build pane, and click “Render Website”

More info here

2) Sending your website to GitHub

1. Go to GitHub.com
2. Start a new repo. I suggest you call it the same as your RStudio project (e.g. my_site or website or something like that)
3. DON’T add a README or a description. We’ll build an empty repo.
4. After you create it, you should see a screen with some git code:

git remote add origin https://github.com/jcvdav/my_site.git
git branch -M main
git push -u origin main

5. Use the code above to push your rendered site (in your RStudio project) to the internet (on your GitHub repository at github.com)

3) Publishing your sebsite

1. Go to settings -> Pages
2. Under branch, select main. And under folder select /docs
3. You are good to go! Your site will be hosted at username.github.io/repo_name

More info here.