install.packages("tinytex")
library(tinytex)
install_tinytex()1 The YAML Header
YAML may be interpreted as either “Yet Another Markup Language” or “YAML Ain’t Markup Language”. YAML is a programming language that typically is for writing configuration files. For a Quarto document, YAML allows us to specify several key elements including document metadata and output file specifications.
1.1 Core Elements
YAML is meant to be human readable. YAML uses whitespace and indentation to structure the the code and works off a principle of key: value. The key is generally some pre-defined element that we want to pass the value to. Keep in mind that YAML is generally case sensitive.
Tip
Working in the RStudio Desktop IDE will provide you with auto-complete for YAML keys as well as allowed values. Use them to your advantage!
When working with YAML in a Quarto document, a good practice is to make sure that the YAML header is at the very top of the QMD file. Further, the YAML header needs to begin and end with lines that contain just three dashes: ---.
The following code block (Listing 1.1) shows the YAML header that was used for the first version of this book (back when it was a single webpage).
---
title: "Quarto Crash Course"
subtitle: "Stat 184"
author: "Neil J. Hatfield"
date: "Dec. 3, 2024"
date-modified: now
format:
html:
embed-resources: true
number-sections: true
toc: true
toc-depth: 4
toc-location: right
fig-align: center
cap-location: top
link-external-newwindow: true
execute:
echo: false
warning: false
csl: apa7.csl
bibliography: references.bib
---The title, subtitle, author, date, and date-modified keys all provide meta-data for the Quarto document.
The format key starts the specifications for how the output files will get generated. In Listing 1.1, I’m customizing the html output with additional keys including using section numbering, including a table of contents (toc), and controlling how figures and captions should appear by default. For HTML documents, you can also specify how links should work; here I’m making sure that they open up in new tabs/windows instead of replacing this guide.
Notice that the the html key is indented in two spaces from the format key and then the sub-keys to html are indented a further two spaces in Listing 1.1. When you are working with sub-keys you need to make sure that you use indentation to help communicate that structure in your YAML code.
The last set of keys that starts with the execute control the defaults for code chunks. Here, I’ve set the code chunks to not print themselves (i.e., echo) and to suppress any warning messages.
Warning
As you draft your documents you might start out with warning: true and then as you reach the end of the drafting cycle switch to warning: false. This will help you see any warnings that R produces for your code so that you address any potential issues.
Important
While there is a sub key of error you can use within the execute, you should avoid ever using this key to hide error messages. You should always see and address any error messages that get generated in your Quarto document.
1.2 Examples
The following examples provide you with some starter YAML headers. You can customize these as needed.
Tip
ALWAYS check with your course instructor or supervisor for what output file and formatting they want.
1.2.1 Using Default Output Formats
Taking a moment to think through what type of output format(s) you want is always a good thing. This fits with the Planning stage of the PCIP System. If the default file formats are all you want, then you can simplify your YAML header. Here are the key: value pairs of the three common default output file types:
- HTML:
format: html - PDF:
format: pdf - Word Doc:
format: docx
If you want Quarto to create multiple output file types from the same document, you use the format key to do this. Listing 1.2 shows a basic example for creating three different output files from one Quarto document.
---
title: "Example Document"
format:
html: default
pdf: default
docx: default
---When specifying multiple output files, you will need to set each output type on their own line and use the default value if you are not otherwise specifying additional formatting guides. You can combine the following examples along with the Listing 1.2.
Note
When creating multiple output files from a single Quarto document, the Render button of RStudio Desktop will only create the first listed output. However, you can use the Terminal to have Quarto generate all output formats. You will either need to make sure that the Terminal is pointed to the folder that your QMD file is in OR provide the full file path. Then, all you need to do is run the following code:
quarto render exampleQuarto.qmd.
1.2.2 HTML w/Code Appendix
If you are planning on including a code appendix (see Chapter 9) in your document, then you do not need to show the code in the body of your document. The following YAML header example (Listing 1.3) serves as a good starting point for HTML output in such a situation.
---
title: "Informative Title"
author: "List All Authors"
date: "Dec. 3, 2024"
date-modified: now
format:
html:
embed-resources: true
number-sections: true
toc: true
toc-depth: 4
toc-location: right
fig-align: center
cap-location: top
link-external-newwindow: true
execute:
echo: false
warning: false
---1.2.3 HTML w/Code Folding
In the event that you are not including a code appendix or you want to allow users to see code chunks in context, then you should set up code folding. This example (Listing 1.4) will give a good starting point for that.
---
title: "Informative Title"
author: "List All Authors"
date: "Dec. 3, 2024"
date-modified: now
format:
html:
embed-resources: true
number-sections: true
toc: true
toc-depth: 4
toc-location: right
fig-align: center
cap-location: top
link-external-newwindow: true
code-fold: true
execute:
warning: false
---Notice that you’ll need to add the code-fold key AND remove the echo key.
1.2.4 PDF
Generally, if you are making a report as a PDF, your code should appear in an appendix at the end of the document, not in the body of your report.
---
title: "Informative Title"
author: "List All Authors"
date: "Dec. 3, 2024"
date-modified: now
format:
pdf:
toc: false
number-sections: true
number-depth: 5
fig-align: center
cap-location: top
geometry:
- top=1in
- left=1in
- right=1in
- bottom=1in
colorlinks: true
execute:
echo: false
warning: false
---When creating a PDF, always check to see if you need a Table of Contents and adjust the toc key’s value as appropriate (Listing 1.5). The geometry key allows you define the page margins. Here, I’ve used 1-inch margins on all sides.
CautionLaTeX Needed
If you are creating a PDF from a Quarto document, you’ll need to have LaTeX installed on your computer. The easiest way to do this is to use TinyTex. The {tinytex} R package will help you install the necessary components.
Running the commands shown in Listing 1.6 in your Console will trigger a process to get LaTeX installed and configured for rendering Quarto documents to PDF. Be sure to follow the prompts as they come up. Keep in mind that the first time you render to a PDF, the process will take a bit longer than usual.
1.2.5 Word
When going to a Microsoft Word document (*.docx), you’ll want to make sure that you do a careful look through the rendered output file to make sure that everything appears how you intended. Be prepared for the need to make adjustments. Listing 1.7 shows a recommended YAML Header.
---
title: "Informative Title"
author: "List All Authors"
date: "Dec. 3, 2024"
date-modified: now
format:
docx:
toc: false
toc-depth: 5
number-sections: true
number-depth: 5
page-width: 6.5
fig-align: center
fig-dpi: 300
execute:
echo: false
warning: false
---As with PDFs, always check to see if a Table of Contents is needed. The page-width key is how you’ll specify the left/right margins (symmetric) for the document. A new key to be sure to set is fig-dpi; this controls the resolution of graphics. Set this too low and your visualizations will appear grainy/fuzzy. The recommendation is to use at least 300.
An additional caution with Word is to check any tables you created. If you are using styling commands from the {kableExtra} package, the tables may not be rendered correctly. You can either switch to another package such as {flextable} or fix the tables in Word.
1.3 Exceptions
Keep in mind that the formatting keys in your YAML header will act as the defaults for your document. You can always override those options for individual pieces. For instance, you can set the default for code chunks to not print themselves (i.e., echo: false) but then have a particular code chunk print itself. These overrides are best done within individual code chunks.
1.4 More with the author Key
YAML allows us some additional flexibility with the author key. Namely, we can use either author or authors as our key and Quarto will know what to do. This allows us to incorporate multiple authors in our report as well as add information about them.