Introduction to Quarto

Part of the course “Track, organize and share your work: An introduction to Git for research”

Slides | Source

Dr. Lennart Wittkuhn

lennart.wittkuhn@uni-hamburg.de

Institute of Psychology, University of Hamburg, Germany

Konrad Pagenstedt

konrad.pagenstedt@studium.uni-hamburg.de

Institute of Psychology, University of Hamburg, Germany

November 29, 2024

Agenda

• Last week: Branches
• Introduction to Quarto
• Basics of Markdown
• The YAML header
• More features
• Quarto in action
• Git integration
• Questions?

Schedule

Last week: Branches

Last week: Branches

lennartwittkuhn.com/version-control-book/chapters/branches.html

This week: Quarto

https://quarto.org

Goals of this session

💡 Learn the basics of the Markdown syntax

💡 Work on a new quarto branch in your city-guide repo

💡 Create a neat new entry file using Quarto

💡 When you are done, merge the changes into your main branch

Outlook: Your Quarto file can later be turned into a website!

See https://lennartwittkuhn.com/uhh-eur-city-guide/

Introduction to Quarto

What is Quarto?

“Publishing system” by Posit ¹

• Based on RMarkdown
• Able to execute code
• Supports multiple programming languages
• Integrated in RStudio

Usecases

• Articles/Reports
• Websites
• Presentations
• Books

Figure 1: A schematic representing the multi-language input (e.g. Python, R, Observable, Julia) and multi-format output (e.g. PDF, html, Word documents, and more) versatility of Quarto. Artwork from “Hello, Quarto” keynote by Julia Lowndes and Mine Çetinkaya-Rundel. Illustrated by Allison Horst (Source).

• Very new (2022)
• Created by Rstudio’s creators
• Like r markdown but for even more features, for example support of Python code, Javascript
• Able to render Markdown files
• publishing system = creating layout of text media and code

Getting started with Quarto

How can you work with Quarto?

You can use one of the following editors:

• RStudio
• Jupyter
• Neovim
• VS Code
• Text editor

Creating a Quarto file in RStudio

1. Download and install the newest version of RStudio
2. Open RStudio
3. Create a new .qmd file: “File” > “New file” > “Quarto Document”

Rendering Quarto files

Output formats

• HTML (standard)
• PDF (requires LaTeX)
• Word (requires MS Word)

Presentations

• reveal.js (HTML)
• Powerpoint (requires MS Powerpoint)

How to render Quarto files

1. Preview

Code

quarto preview

• The document will be rendered and a web browser with a “live preview” opened
• Position this browser so that you can see it as you edit and save the document
• Every time you save, the preview will be updated
• Windows Users: Note, that quarto preview might not work in Git Bash! Use the Render buttons in RStudio (see right column)

2. Render

Code

quarto render

• Render a document (or group of documents) without previewing them
• You can also use the Render button in RStudio and enable Render on Save

Your turn

Task 1

1. Create a new quarto branch in your city-guide repository and switch to it

Remember, that quarto is just a branch name here. You can also choose a different name for the branch if you want to.

Task 2

1. Create a new empty Quarto file called city-guide.qmd and save it in your city-guide repository
2. Write a short introduction note to your city-guide repository
3. Switch between Quarto’s visual and source mode
4. Render the file to HTML
5. Stage and commit your new file

Your turn

Task 2.1

Quarto and RStudio might create a bunch of extra files:

.Rproj.user
.Rhistory
.RData
.Ruserdata
/_site/
/.quarto/

The are temporary or user specific files and should therefore not be tracked in Git.

1. Add any file that is not the .qmd file to your .gitignore file.
2. Stage and commit the changes to your .gitignore file.

Basics of Markdown

Markdown

• Easy to use
• “Markup” language
• Content and formatting are integrated, not separated
• Alternative to “What You See Is What You Get” (WYSIWYG) editors like MS Word
• Used by text editors, GitHub (e.g., READMEs), and more
• Integrated in RStudio as “RMarkdown”

Example: HedgeDoc

• Markup Language = text encoding system readable by machine
• Pros:
  • easier to use for quick notes
  • faster to write since format and content intertwined
  • version control
  • faster
  • less loading
• Cons:
  • less formatting options since its intentionally simple, e.g. tables pretty complex to do, or pictures less intuitive (once used to word)
• Used by: GitHub, Slack Discord, Reddit Hedgedoc = open source markdown editor
• Formerly knows as CodiMD
• RMarkdown: designed to be used with R from Rstudio
• integration of R code, create documents which include code, widely used in scientific community

Text Formatting

Input	Output
*italics* and **bold**	italics and bold
superscript^2^ / subscript~2~	superscript2 / subscript2
~~strikethrough~~	strikethrough
`verbatim code`	verbatim code

Headings

Input	Output
# Header 1	Header 1
## Header 2	Header 2
### Header 3	Header 3
#### Header 4	Header 4
##### Header 5	Header 5
###### Header 6	Header 6

Lists

Input	Output
* unordered list + sub-item 1 + sub-item 2	unordered list sub-item 1 sub-item 2
1. ordered list 2. item 2 1. sub-item 1	ordered list item 2 sub-item 1
1. ordered list 1. item 2 1. item 3 1. item 4	ordered list item 2 item 3 item 4

Tables

Input	Output
| 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

💡 Tip: Use a Markdown table generator

Equations

Markdown Syntax	Output
inline math: $E = mc^{2}$	E=mc^{2}
display math: $$E = mc^{2}$$	E = mc^{2}

Blocks

Input	Output
> Blockquote	Blockquote

Links and images

Input	Output
<https://quarto.org/>	https://quarto.org/
[Quarto](https://quarto.org/)	Quarto
[](https://quarto.org)

Task 3

1. Add a new entry to the city-guide.qmd file
2. Topic: Interview each other about your favorite cinema or theater.
3. Format the text by applying at least three types of Markdown syntax
4. Stage and commit your changes

The YAML header

YAML

• Document settings: YAML sets up document settings like title, author, and output format.
• Customization: Use YAML for themes and styling.
• Specify themes: for example, “default” or “morph”

Examples

---
title: "Document title"
author: "Your Name"
theme: vapor
format: pdf
--- 

The YAML header of these slides:

---
title: "Introduction to Quarto"
subtitle: |
  Part of the course “Track, organize and share your work: An introduction to Git for research”
  
  [Slides](https://lennartwittkuhn.com/) |
  [Source](https://github.com/lnnrtwttkhn/)
  
  License: CC BY 4.0
  DOI
theme: default
date: today

• YAML: Datenformat in konfiguartionsdateien
• viele andere Anwendungsmöglichkeiten,
• Metadata for files, today only author, title and output format and Theme
• Could also do e.g. date:

Task 4

1. Add a YAML header to your Quarto file
2. Include your name, a title, an output format (e.g., HTML) and a theme
3. Stage and commit your changes

When you are done and your Quarto file is rendering properly:

4. Merge your quarto branch into your default branch (main or master)

More features

Code chunks

• Executable code: Quarto files support code execution during rendering
• Code chunks can be interactive
• Customizable options: Specify various options for code chunks
• You can also use inline code
• R code enclosed by: ```{r} code ```

Examples

Input

x <- c(1, 2, 3, 4, 5)
y <- c(2, 4, 1, 3, 5)
plot(x, y, main = "Scatter Plot Example", xlab = "X-Axis", ylab = "Y-Axis")

Output

Inline code

Input

Code

Number of observations: `r 8*20`

Output

Number of observations: 160

Code: you don’t have to use it for a new entry book but its possible

Referencing

• You can name and references objects like figures, tables etc.
• For example: Section 5.4 (@sec-citations)

Type	Label Prefix
Figures	fig-
Tables	tbl-
Equations	eq-
Sections	sec-
Code listing	lst-
Theorem	thm-

Citations

• Citations can be added via Insert > Citation
• Citations can also be added directly with @
• References are stored in BibTeX files in your project

Markdown Format	Output (author-date format)
Blip blop bloop [see @chacon2014, pp. 33-35; also @ggseg, chap. 1]	Blip blop bloop [see Chacon and Straub (2014), pp. 33-35; also , chap. 1]
Blip blop bloop [@chacon2014, pp. 33-35, 38-39 and passim]	Blip blop bloop (Chacon and Straub 2014, 33–35, 38–39 and passim)
Blip blop bloop [@chacon2014].	Blip blop bloop (Chacon and Straub 2014).
They say blah [-@chacon2014]	Lennart says blah (2014)
@chacon2014 says bloop.	Chacon and Straub (2014) says bloop.

Quarto in action

Usescases for researchers

• Reproducible papers
• Data analysis & visualization
• Dynamic documents
• Presentation slides
• Automated reports

Git integration

Using Git with .qmd files

Features

• Plain Text Files: .qmd files are plain text, ensuring compatibility with git diff
• Branching and Merging: Use Git’s branching and merging capabilities to manage complex document edits.
• Conflict Resolution: Resolve conflicts efficiently when collaborating on .qmd files
• RStudio Integration: RStudio offers a graphical user interface (GUI) for Git integration

GitHub Actions

• Workflow Automation Can automate various tasks, including document generation.
• Trigger Events: Specify events, such as pushes or pull requests, to trigger document generation automatically.
• Can allow you to easily update website built with Quarto (hosted with GitHub pages)

Further reading

• Official Quarto Documentation
• Quartaki by Dr. Mowinckel
• Awesome Quarto (Resource Collection)

References

Chacon, Scott, and Ben Straub. 2014. Pro Git. Apress. https://doi.org/10.1007/978-1-4842-0076-6.

Questions?

Footnotes

1. (the company formerly known as RStudio)