01-Baby Steps

YAML

The overall appearance and behavior of the document is specified in the YAML:

HTML default YAML

---
title: "Untitled"
format: html
editor: visual
---

. . .

PDF default YAML

---
title: "Untitled"
format: pdf
editor: visual
---

Source vs. Visual

Editor

knitr::include_graphics("img/q_source.png")

Visual

knitr::include_graphics("img/q_visual.png")

YAML: Table of Contents (ToC)

---
title: "My quarto file"
author: "Jane Doe"
date: today
format: 
  html:
    self-contained: true     # 1
    toc: true                # 2   
    toc-title: My contents   # 3
    toc-location: left       # 4
lang: it                     # 5
---

1. Allows for the sharing of the hmtl file without requiring for external files

2. Put Table of Contents

3. Define the title of the ToC

4. Location of the ToC (left, right, body)

5. Define the language of the documents

Themes

The default theme of the document can be modified with the predefined themes

---
title: "My quarto file"
author: "Jane Doe"
date: today
format: 
  html:
    self-contained: true     
    toc: true                   
    toc-title: My contents   
    toc-location: left
    theme: superhero  # 1
    fontsize: 32px    # 2 customization
lang: it                     
---

1. Define the theme

2. Define the font size (other options are available)

Day vs night

---
format: 
  html:
    theme:
     light: minty
     dark: superhero
---

Day

knitr::include_graphics("img/light.png")

Night

knitr::include_graphics("img/dark.png")

Markdown formatting

Headings

# First level

Section

## Second level

Subsection

### Third level

Sub-subsection

#### Fourth level

Paragraph

##### Fifth level

I frankly have never used that

##### Sixth level

I have no idea

Text Formatting

Markdown syntax: Font

*italics*, **bold**, ***bold italics*** 

Output

italics, bold, bold italics

. . .

Markdown syntax: Scripts

textsuperscirpt^2^, textunderscript~2~

Output

textsuperscirpt², textunderscript₂

. . .

Markdown syntax: In line code

`this is myinline code`

Output

this is myinline code

Links and images

<https://github.com/>

https://github.com/

. . .

My link is [here](https://github.com/)

My link is here

. . .

![This is an image](img/picture.jpg)

This is an image

Lists

* Main Unordered List
  + First sub-item
  + Second sub-item 
    - It's getting weird

1. Main ordered list
2. Second item
   i) First sub-item 1
      A.  First sub-sub-item 1

- [ ] First things first 1
- [ ] Second things second 2

• Main Unordered List
  • First sub-item
  • Second sub-item
    • It’s getting weird

1. Main ordered list
2. Second item
   1. First sub-item 1
      1. First sub-sub-item 1
         

• First things first 1
• Second things second 2

Math

In-line math:

This is an in-line equation $y = \beta_0 + \beta_1 X + \varepsilon$

This is an in-line equation \(y = \beta_0 + \beta_1 X + \varepsilon\)

. . .

Math math:

This is an  equation $$z = \dfrac{\bar{x} -\mu}{\sigma}$$

This is an equation \[z = \dfrac{\bar{x} -\mu}{\sigma}\]

References

YAML

Define the path of the bib file in the YAML

[...]
bibliography: references.bib

.bib file

@Manual{rsoft,
    title = {R: A Language and Environment for Statistical Computing},
    author = {{R Core Team}},
    organization = {R Foundation for Statistical Computing},
    address = {Vienna, Austria},
    year = {2025},
    url = {https://www.R-project.org/}
}
@Book{ggplot,
    author = {Hadley Wickham},
    title = {ggplot2: Elegant Graphics for Data Analysis},
    publisher = {Springer-Verlag New York},
    year = {2016},
    isbn = {978-3-319-24277-4},
    url = {https://ggplot2.tidyverse.org}
}
@article{epifania2024,
  title={A guided tutorial on linear mixed-effects models for the analysis of accuracies and response times in experiments with fully crossed design.},
  author={Epifania, Ottavia M and Anselmi, Pasquale and Robusto, Egidio},
  journal={Psychological Methods},
  year={2024},
  publisher={American Psychological Association}, 
  doi={https://doi.org/10.1037/met0000708}
}

Citation keys

Key	Output
@ggplot does this	Wickman (2016) does this
ggplot2 is an interesting package [@ggplot2]	ggplot2 is an interesting package (Wickman, 2016)
bla bla bla [@epifania2024; @ggplot2]	bla bla bla (Epifania et al., 2024; Wickman, 2016)

. . .

To call a reference:

@citaton-key

Publish your HTML document (with GitHub)

GitHub pages

Navigate to your GitHub repository online:

knitr::include_graphics("img/pages-git.png")

It worked!

knitr::include_graphics("img/pages.png")

(take some time, be patient)

README.md

This file handles the generation of the website

It works with basic markdown syntax

README.md

knitr::include_graphics(path = "img/readme.png")

Site appearance

knitr::include_graphics(path = "img/site.png")

Links

They create the index to the pages we want to display in our website

Warning

The links must link to the directory of the html file in the subfolder of the project!

. . .

Let’s say we want to create a link to my_file.html that is inside the files subfolder:

[My presentation](files/my_file.html)

Don’t forget to save the changes in the README.md file

commit + push

knitr::include_graphics("img/commit1.png")

knitr::include_graphics("img/commit2.png")

Don’t forget to push!

Check

knitr::include_graphics("img/check-commit.png")

Your turn!

Inside your R project for this school:

• Create a new HMTL quarto document that must contain:

  • 3 sections (level I heading), each with a subsection (level II heading)
  • Place a picture with a caption in one of the subsection
  • Place an unordered list

• Render the document in HTML

• Create the link to your newly created document in the README.md

• Commit & push the .qmd and .html of your newly created document

• Commit & push the .md and .html of the README file

Layout

By default, the HTML document is set to take all the space in the page

format: 
  html:
    page-layout: full

knitr::include_graphics("img/basic-layout.png")

Document layout

A document

knitr::include_graphics("img/adavanced-layout.png")

Code

format: 
  html: 
   toc: true
   toc-location: left
   grid:
    sidebar-width: 300px
    body-width: 900px
    margin-width: 300px
    gutter-width: 1.5rem

Margins

You can place anything in the margins of the documents!

:::{.column-margin}
I want this picture displayed in the margin 


![](img/peacock.png)
:::

knitr::include_graphics("img/margins.png")

Even references

Output

knitr::include_graphics("img/margin-ref.png")

Code

YAML:

citation-location: margin

Citation:

`ggplot2` is an R [@rsoft] package developed by [@ggplot]. @epifania2024 published an interesting paper on Linear Mixed Effects Models. 

Custom layout with grid

The page layout is based on a 12-unit (or 12-column) grid system, which can be used to divide the space accordingly:

Code

::: {.grid}

::: {.g-col-4}

First column, 4/12 of the total width

:::

::: {.g-col-8}

Second column, 8/12 of the total width 

:::

:::

Output

knitr::include_graphics("img/grid.png")

Columns

Code

:::: {.columns}


::: {.column width="50%"}

This is my first column!

:::

::: {.column width="50%"}

And this is the second column
:::

::::

Output

This is my first column!

And this is the second column

(Best for HMTL presentation)

tabset: code

::: {.panel-tabset}

## Aim

Here I present the aim of the study 

## Methods

Here I present the methods used to pursue the aim

## Results

And here I present the results

:::

tabset: output

Aim

Here I present the aim of the study

Methods

Here I present the methods used to pursue the aim

Results

And here I present the results

Callout

Output

Note

To say something general

I’m a title!

Maybe a tip :)

Pay attention!

Please pay attention to whatever it is written here

Warning

Just saying you should be careful

Code

::: {.callout-note}
To say something general
:::

::: {.callout-tip}
## I'm a title!

Maybe a tip :)
:::

::: {.callout-caution}
## Pay attention!

Please pay attention to whatever it is written here
:::


::: {.callout-warning}
Just saying you should be careful
:::

Collapsing & Other amenities

Output

Look at me!!

I collapse (Actually you can’t see the callout collapsing, just copy & paste in your file)

I’m not an icon

I removed the icon from this specific callout. If you want to remove the icons from all the blocks, go in the YAML, and on a new line (not indented):

callout-icon: false

Code

::: {.callout-warning collapse="true"}

## Look at me!!

I collapse (Actually you can't see the callout collapsing, just copy & paste in your file)

:::


::: {.callout-tip icon="false"}
## I'm not an icon

I removed the icon from this specific callout. 

If you want to remove the icons from **all** the blocks, go in the YAML: 


:::

Your turn

From the previous document:

• In one of the sections, create a grid dividing the space in 3 intervals of different width
• Place a picture in each of the three intervals
• In a subsection:
  • Create a panel tabset with 3 tabs (like Introduction, Methods, Results)
  • Add a picture in the margin of the document
• Go grazy with the callout