2  Quarto intro

beginner
basics
About this chapter
This chapter is an introduction to Quarto

2.1 What is Quarto?

Quarto is an open-source, multi-language, publishing system created by Posit (formerly known as RStudio). It is designed to enable the creation of dynamic documents, including reports, presentations, websites, books, and more. Quarto builds upon the foundation of RMarkdown, extending its capabilities to support multiple programming languages and various output formats. Quarto integrates code, text, and media into a single document that can be rendered into various formats. It supports languages like R, Python, Julia, and JavaScript, making it ideal for scientific writing, data analysis, and technical documentation. This chapter introduces the basics of Quarto, its features, and how to get started using it for your projects.

2.1.1 Key Features

  • Multi-language support: Quarto allows the integration of code from different programming languages in a single document.

  • Output formats: Quarto can generate HTML, PDF, Word documents, presentations (using reveal.js or PowerPoint), and even websites.

  • Integration with RStudio: Quarto is deeply integrated with RStudio, making it easy to create and render documents within this IDE.

2.1.2 Common Use Cases

  • Articles and Reports: Quarto is widely used for creating dynamic articles and reports that can include code, figures, and references.

  • Websites: You can use Quarto to build entire websites, integrating multiple pages and even blogs.

  • Presentations: Quarto allows you to create interactive presentations with support for multimedia content.

  • Books: You can use Quarto to write and publish online books, with support for multiple chapters, references, and more.

2.2 Getting started with Quarto

To begin using Quarto, you need to have an appropriate text editor installed. Quarto supports various editors, including RStudio, Jupyter, Neovim, Visual Studio Code (VS Code), and even plain text editors like e.g. Vim.

2.2.1 Using Quarto from RStudio

  1. Install RStudio: Download and install the latest version of RStudio from the Posit website.

  2. Create a Quarto file: Open RStudio and navigate to “File” > “New file” > “Quarto Document” to create a new .qmd file.

2.2.2 Rendering Quarto Documents

Quarto documents can be rendered into different formats using either the command line or the RStudio GUI.

  • Preview You can preview your Quarto document in a web browser that updates live as you make changes using:
quarto preview

This command opens a live preview of your document in a web browser. The preview automatically updates each time you save the document. If you open your quarto file in Rstudio there is also a render button at the top of the GUI.

  • Render: To render your document without previewing, use:
quarto render

This command generates the final output based on the specified format in the YAML header (e.g., HTML, PDF).

Where to run these commands: Open your terminal or command prompt and navigate to the directory where your Quarto file (e.g., your-document.qmd) is located.

2.3 Markdown Basics

Quarto uses Markdown, a lightweight markup language, for formatting text. Markdown is easy to learn and widely used in various platforms, including GitHub, Slack, and RStudio.

2.3.1 Text Formatting

Markdown allows you to easily format text. Here are some common formatting options:

  • Bold: **bold text**
  • Italic: *italicized text*
  • Code: `code`
  • Blockquote: > blockquote

2.3.2 Lists

Markdown supports both ordered and unordered lists:

  • Unordered list:

    - Item 1
- Item 2
- Item 3

  • Ordered list:

    1. First item
2. Second item
3. Third item

2.3.3 Tables

You can create tables in Markdown using the following syntax:

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

2.3.4 Equations

Quarto supports LaTeX syntax for rendering mathematical equations:

  • Inline math: $E = mc^{2}$

  • Display math:

    $$E = mc^{2}$$

2.4 Useful features

2.4.1 YAML Header

The YAML header at the beginning of a Quarto document contains metadata that controls how the document is rendered. This includes the title, author, date, and output format.

2.4.2 Example YAML Header

---
title: "Document Title"
author: "Your Name"
format: html
theme: default
---

2.4.3 Code Chunks

One of the key features of Quarto is the ability to include executable code chunks within your document. These chunks can be written in various programming languages and are executed during rendering.

2.4.3.1 Example Code Chunk:

Code
# Example Code Chunk
# This is an R code chunk that generates a scatter plot
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")

This code will be executed when the document is rendered, and the output (a scatter plot) will be included in the final document.

2.5 Git Integration

Quarto documents (.qmd files) are plain text, making them ideal for version control using Git. You can take advantage of Git’s branching and merging capabilities to manage complex document edits and resolve conflicts efficiently. Check out our Version Control Book for more information about hwo to use Git.

2.6 Conclusion

Quarto is a powerful tool that brings together the best features of Markdown, RMarkdown, and modern programming environments to create dynamic, reproducible documents. Whether you’re writing a research paper, building a website, or preparing a presentation, Quarto provides the tools you need to streamline your workflow and enhance your output. By mastering the basics covered in this chapter, you’ll be well on your way to using Quarto effectively in your own projects.