r4ds/quarto-formats.qmd

281 lines
11 KiB
Plaintext
Raw Normal View History

# Quarto formats {#sec-quarto-formats}
```{r}
#| results: "asis"
#| echo: false
2023-03-12 00:26:05 +08:00
source("_common.R")
2023-01-23 21:55:51 +08:00
status("complete")
```
2016-08-22 22:31:17 +08:00
2016-08-23 21:59:08 +08:00
## Introduction
So far, you've seen Quarto used to produce HTML documents.
This chapter gives a brief overview of some of the many other types of output you can produce with Quarto.
There are two ways to set the output of a document:
2016-08-22 22:31:17 +08:00
1. Permanently, by modifying the YAML header:
``` yaml
title: "Diamond sizes"
format: html
2016-08-23 06:28:29 +08:00
```
2. Transiently, by calling `quarto::quarto_render()` by hand:
```{r}
#| eval: false
2016-08-22 22:31:17 +08:00
quarto::quarto_render("diamond-sizes.qmd", output_format = "docx")
```
This is useful if you want to programmatically produce multiple types of output since the `output_format` argument can also take a list of values.
2016-08-23 06:28:29 +08:00
```{r}
#| eval: false
quarto::quarto_render("diamond-sizes.qmd", output_format = c("docx", "pdf"))
```
2016-08-22 22:31:17 +08:00
2016-08-23 06:28:29 +08:00
## Output options
2016-08-22 22:31:17 +08:00
Quarto offers a wide range of output formats.
You can find the complete list at <https://quarto.org/docs/output-formats/all-formats.html>.
2023-04-10 23:22:08 +08:00
Many formats share some output options (e.g., `toc: true` for including a table of contents), but others have options that are format specific (e.g., `code-fold: true` collapses code chunks into a `<details>` tag for HTML output so the user can display it on demand, it's not applicable in a PDF or Word document).
2016-08-22 22:31:17 +08:00
To override the default options, you need to use an expanded `format` field.
For example, if you wanted to render an `html` with a floating table of contents, you'd use:
2016-08-22 22:31:17 +08:00
``` yaml
format:
html:
2016-08-23 06:28:29 +08:00
toc: true
toc_float: true
```
2016-08-22 22:31:17 +08:00
2016-08-26 05:44:14 +08:00
You can even render to multiple outputs by supplying a list of formats:
2016-08-22 22:31:17 +08:00
``` yaml
format:
html:
2016-08-23 06:28:29 +08:00
toc: true
toc_float: true
pdf: default
docx: default
2016-08-23 06:28:29 +08:00
```
2016-08-22 22:31:17 +08:00
Note the special syntax (`pdf: default`) if you don't want to override any default options.
2016-08-22 22:31:17 +08:00
To render to all formats specified in the YAML of a document, you can use `output_format = "all"`.
2016-08-22 22:31:17 +08:00
```{r}
#| eval: false
quarto::quarto_render("diamond-sizes.qmd", output_format = "all")
```
## Documents
The previous chapter focused on the default `html` output.
There are several basic variations on that theme, generating different types of documents.
For example:
- `pdf` makes a PDF with LaTeX (an open-source document layout system), which you'll need to install.
RStudio will prompt you if you don't already have it.
- `docx` for Microsoft Word (`.docx`) documents.
- `odt` for OpenDocument Text (`.odt`) documents.
2016-08-22 22:31:17 +08:00
- `rtf` for Rich Text Format (`.rtf`) documents.
2016-08-22 22:31:17 +08:00
- `gfm` for a GitHub Flavored Markdown (`.md`) document.
- `ipynb` for Jupyter Notebooks (`.ipynb`).
2016-08-22 22:31:17 +08:00
Remember, when generating a document to share with decision-makers, you can turn off the default display of code by setting global options in document YAML:
2016-08-22 22:31:17 +08:00
``` yaml
execute:
echo: false
2016-08-22 22:31:17 +08:00
```
For `html` documents another option is to make the code chunks hidden by default, but visible with a click:
2016-08-22 22:31:17 +08:00
``` yaml
format:
html:
code: true
2016-08-23 21:59:08 +08:00
```
2016-08-22 22:31:17 +08:00
2016-08-23 21:59:08 +08:00
## Presentations
2016-08-22 22:31:17 +08:00
You can also use Quarto to produce presentations.
You get less visual control than with a tool like Keynote or PowerPoint, but automatically inserting the results of your R code into a presentation can save a huge amount of time.
Presentations work by dividing your content into slides, with a new slide beginning at each second (`##`) level header.
Additionally, first (`#`) level headers indicate the beginning of a new section with a section title slide that is, by default, centered in the middle.
2016-08-22 22:31:17 +08:00
Quarto supports a variety of presentation formats, including:
2016-08-22 22:31:17 +08:00
1. `revealjs` - HTML presentation with revealjs
2016-08-22 22:31:17 +08:00
2. `pptx` - PowerPoint presentation
2016-08-22 22:31:17 +08:00
3. `beamer` - PDF presentation with LaTeX Beamer.
2016-08-23 21:59:08 +08:00
You can read more about creating presentations with Quarto at [https://quarto.org/docs/presentations](https://quarto.org/docs/presentations/).
2016-08-23 06:28:29 +08:00
2016-08-23 21:59:08 +08:00
## Interactivity
2016-08-22 22:31:17 +08:00
2023-03-12 00:26:05 +08:00
Just like any HTML document, HTML documents created with Quarto can contain interactive components as well.
Here we introduce two options for including interactivity in your Quarto documents: htmlwidgets and Shiny.
2016-08-22 22:31:17 +08:00
2016-08-23 21:59:08 +08:00
### htmlwidgets
2016-08-22 22:31:17 +08:00
HTML is an interactive format, and you can take advantage of that interactivity with **htmlwidgets**, R functions that produce interactive HTML visualizations.
For example, take the **leaflet** map below.
If you're viewing this page on the web, you can drag the map around, zoom in and out, etc.
You obviously can't do that in a book, so Quarto automatically inserts a static screenshot for you.
2016-08-22 22:31:17 +08:00
2016-08-23 21:59:08 +08:00
```{r}
library(leaflet)
2022-02-24 03:15:52 +08:00
leaflet() |>
setView(174.764, -36.877, zoom = 16) |>
addTiles() |>
2016-10-03 21:23:00 +08:00
addMarkers(174.764, -36.877, popup = "Maungawhau")
2016-08-23 21:59:08 +08:00
```
2016-08-22 22:31:17 +08:00
The great thing about htmlwidgets is that you don't need to know anything about HTML or JavaScript to use them.
All the details are wrapped inside the package, so you don't need to worry about it.
2016-08-22 22:31:17 +08:00
2016-08-23 21:59:08 +08:00
There are many packages that provide htmlwidgets, including:
2016-08-22 22:31:17 +08:00
2023-03-12 00:26:05 +08:00
- [**dygraphs**](https://rstudio.github.io/dygraphs) for interactive time series visualizations.
2016-08-22 22:31:17 +08:00
2023-03-12 00:26:05 +08:00
- [**DT**](https://rstudio.github.io/DT/) for interactive tables.
2016-08-22 22:31:17 +08:00
2023-03-12 00:26:05 +08:00
- [**threejs**](https://bwlewis.github.io/rthreejs) for interactive 3d plots.
2016-08-23 21:59:08 +08:00
2023-03-12 00:26:05 +08:00
- [**DiagrammeR**](https://rich-iannone.github.io/DiagrammeR) for diagrams (like flow charts and simple node-link diagrams).
2016-08-23 21:59:08 +08:00
To learn more about htmlwidgets and see a complete list of packages that provide them visit <https://www.htmlwidgets.org>.
2016-08-23 21:59:08 +08:00
### Shiny
htmlwidgets provide **client-side** interactivity --- all the interactivity happens in the browser, independently of R.
On the one hand, that's great because you can distribute the HTML file without any connection to R.
However, that fundamentally limits what you can do to things that have been implemented in HTML and JavaScript.
An alternative approach is to use **shiny**, a package that allows you to create interactivity using R code, not JavaScript.
2016-08-23 21:59:08 +08:00
To call Shiny code from a Quarto document, add `server: shiny` to the YAML header:
2016-08-23 21:59:08 +08:00
``` yaml
2016-08-23 21:59:08 +08:00
title: "Shiny Web App"
format: html
server: shiny
2016-08-23 21:59:08 +08:00
```
Then you can use the "input" functions to add interactive components to the document:
```{r}
#| eval: false
2016-08-23 21:59:08 +08:00
library(shiny)
textInput("name", "What is your name?")
numericInput("age", "How old are you?", NA, min = 0, max = 150)
2016-08-23 06:28:29 +08:00
```
And you also need a code chunk with chunk option `context: server` which contains the code that needs to run in a Shiny server.
```{r}
#| echo: false
#| out-width: null
#| fig-alt: |
#| Two input boxes on top of each other. Top one says, "What is your
#| name?", the bottom, "How old are you?".
knitr::include_graphics("quarto/quarto-shiny.png")
2016-08-26 05:44:14 +08:00
```
2016-08-23 21:59:08 +08:00
You can then refer to the values with `input$name` and `input$age`, and the code that uses them will be automatically re-run whenever they change.
2022-08-10 00:43:12 +08:00
We can't show you a live shiny app here because shiny interactions occur on the **server-side**.
This means that you can write interactive apps without knowing JavaScript, but you need a server to run them on.
This introduces a logistical issue: Shiny apps need a Shiny server to be run online.
When you run Shiny apps on your own computer, Shiny automatically sets up a Shiny server for you, but you need a public-facing Shiny server if you want to publish this sort of interactivity online.
That's the fundamental trade-off of shiny: you can do anything in a shiny document that you can do in R, but it requires someone to be running R.
2016-08-23 21:59:08 +08:00
For learning more about Shiny, we recommend reading Mastering Shiny by Hadley Wickham, [https://mastering-shiny.org](https://mastering-shiny.org/).
## Websites and books
2016-08-23 21:59:08 +08:00
With a bit of additional infrastructure, you can use Quarto to generate a complete website or book:
2016-08-23 21:59:08 +08:00
- Put your `.qmd` files in a single directory.
`index.qmd` will become the home page.
2016-08-26 05:44:14 +08:00
- Add a YAML file named `_quarto.yml` that provides the navigation for the site.
2022-12-09 04:41:37 +08:00
In this file, set the `project` type to either `book` or `website`, e.g.:
2016-08-23 21:59:08 +08:00
``` yaml
project:
type: book
2016-08-23 21:59:08 +08:00
```
For example, the following `_quarto.yml` file creates a website from three source files: `index.qmd` (the home page), `viridis-colors.qmd`, and `terrain-colors.qmd`.
```{r}
#| echo: false
#| comment: ""
2016-08-23 05:08:16 +08:00
cat(readr::read_file("quarto/example-site.yml"))
```
The `_quarto.yml` file you need for a book is very similarly structured.
The following example shows how you can create a book with four chapters that renders to three different outputs (`html`, `pdf`, and `epub`).
Once again, the source files are `.qmd` files.
```{r}
#| echo: false
#| comment: ""
cat(readr::read_file("quarto/example-book.yml"))
```
We recommend that you use an RStudio project for your websites and books.
Based on the `_quarto.yml` file, RStudio will recognize the type of project you're working on, and add a Built tab to the IDE that you can use to render and preview your websites and books.
Both websites and books can also be rendered using `quarto::render()`.
Read more at <https://quarto.org/docs/websites> about Quarto websites and <https://quarto.org/docs/books> about books.
## Other formats
2016-08-23 05:08:16 +08:00
Quarto offers even more output formats:
2016-08-23 21:59:08 +08:00
- You can write journal articles using Quarto Journal Templates: <https://quarto.org/docs/journals/templates.html>.
2016-08-24 05:40:48 +08:00
- You can output Quarto documents to Jupyter Notebooks with `format: ipynb`: <https://quarto.org/docs/reference/formats/ipynb.html>.
2016-08-24 05:40:48 +08:00
See <https://quarto.org/docs/output-formats/all-formats.html> for a list of even more formats.
2016-08-23 21:59:08 +08:00
2023-03-12 00:26:05 +08:00
## Summary
In this chapter we presented you a variety of options for communicating your results with Quarto, from static and interactive documents to presentations to websites and books.
2016-08-23 05:08:16 +08:00
To learn more about effective communication in these different formats, we recommend the following resources:
2016-08-23 05:08:16 +08:00
- To improve your presentation skills, try [*Presentation Patterns*](https://presentationpatterns.com/) by Neal Ford, Matthew McCollough, and Nathaniel Schutta.
It provides a set of effective patterns (both low- and high-level) that you can apply to improve your presentations.
2022-08-10 00:43:12 +08:00
- If you give academic talks, you might like the [*Leek group guide to giving talks*](https://github.com/jtleek/talkguide).
2022-12-09 04:41:37 +08:00
- We haven't taken it ourselves, but we've heard good things about Matt McGarrity's online course on public speaking: <https://www.coursera.org/learn/public-speaking>.
- If you are creating many dashboards, make sure to read Stephen Few's [*Information Dashboard Design: The Effective Visual Communication of Data*](https://www.amazon.com/Information-Dashboard-Design-Effective-Communication/dp/0596100167).
It will help you create dashboards that are truly useful, not just pretty to look at.
2016-08-23 05:08:16 +08:00
- Effectively communicating your ideas often benefits from some knowledge of graphic design.
Robin Williams' [*The Non-Designer's Design Book*](https://www.amazon.com/Non-Designers-Design-Book-4th/dp/0133966151) is a great place to start.