07:00
Quarto - authoring and publishing tools for collaborative scientific writing
April 3, 2024
Metadata: YAML
Text: Markdown
Code: Executed via knitr
or jupyter
Weave it all together, and you have beautiful, powerful, and useful outputs!
Literate programming is writing out the program logic in a human language with included (separated by a primitive markup) code snippets and macros.
“Yet Another Markup Language” or “YAML Ain’t Markup Language” is used to provide document level metadata.
Indentation matters!
:
There are multiple ways of formatting valid YAML:
:
format: html
with selections made with proper indentationLint, or a linter, is a static code analysis tool used to flag programming errors, bugs, stylistic errors and suspicious constructs.
RStudio + VSCode provide rich tab-completion - start a word and tab to complete, or Ctrl + space
to see all available options.
Many YAML fields are common across various outputs
But also each output type has its own set of valid YAML fields and options
Definitive list: quarto.org/docs/reference/formats/html
Markdown Syntax | Output |
---|---|
|
italics and bold |
|
superscript2 / subscript2 |
|
|
|
verbatim code |
Markdown Syntax | Output |
---|---|
|
Header 1 |
|
Header 2 |
|
Header 3 |
|
Header 4 |
|
Header 5 |
|
Header 6 |
There are several types of “links” or hyperlinks.
Markdown
Output
You can embed named hyperlinks, direct urls like https://quarto.org/, and links to other places in the document. The syntax is similar for embedding an inline image: .
Unordered list:
Output
Ordered list:
Markdown:
> Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.
> - Donald Knuth, Literate Programming
Output:
Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. - Donald Knuth, Literate Programming
markdown-syntax.qmd
in RStudio.07:00
::: callout-note
Note that there are five types of callouts, including:
`note`, `tip`, `warning`, `caution`, and `important`.
:::
Note
Note that there are five types of callouts, including: note
, tip
, warning
, caution
, and important
.
Warning
Callouts provide a simple way to attract attention, for example, to this warning.
Important
Danger, callouts will really improve your writing.
Caution
Here is something under construction.
Caption
Tip with caption.
callout-boxes.qmd
and render the document.How to edit the options?
07:00
Numbering and formatting footnotes is supported.
Here is an inline note.^[Inlines notes are easier to write,
since you don't have to pick an identifier and move down to
type the note.]
Here is an inline note.1
Use the source editor mode
The source editor mode is the recommended way to add footnotes.
r
) is indicated between curly braces {r}
#|
(hashpipe)echo
echo
option shows the code when set to true
and hides it when set to false
.In reproducible reports and manuscripts, the most commonly included code outputs are tables and figures.
So they get their own special sections in our deep dive!
Markdown:
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
| 1 | 1 | 1 | 1 |
Use the source editor mode
The source editor mode is the recommended way to add markdown tables. These are tables, which are not generated from code.
Output:
Right | Left | Default | Center |
---|---|---|---|
12 | 12 | 12 | 12 |
123 | 123 | 123 | 123 |
1 | 1 | 1 | 1 |
The knitr package can turn data frames into tables with knitr::kable()
:
If you want fancier tables, try the gt package and all that it offers!
species | island | bill_length_mm | bill_depth_mm | flipper_length_mm | body_mass_g | sex | year |
---|---|---|---|---|---|---|---|
Adelie | Torgersen | 39.1 | 18.7 | 181 | 3750 | male | 2007 |
Adelie | Torgersen | 39.5 | 17.4 | 186 | 3800 | female | 2007 |
Adelie | Torgersen | 40.3 | 18.0 | 195 | 3250 | female | 2007 |
Adelie | Torgersen | NA | NA | NA | NA | NA | 2007 |
Adelie | Torgersen | 36.7 | 19.3 | 193 | 3450 | female | 2007 |
Adelie | Torgersen | 39.3 | 20.6 | 190 | 3650 | male | 2007 |
![Penguins playing with a Quarto ball](images/penguins-quarto-ball.png)
Penguins playing with a Quarto ball
Markdown:
::: {#fig-penguins layout-ncol=2}
![Blue penguin](images/blue-penguin.png){#fig-blue width="250px"}
![Orange penguin](images/orange-penguin.png){#fig-orange width="250px"}
Two penguins
:::
Output:
In places like markdown, YAML, or the command line/shell/terminal, you’ll need to use absolute or relative file paths:
"/Users/lars/exercises"
- Whose computer will this work on?Relative = BETTER:
"../
= up one directory, ../../
= up two directories, etc./..
or /
= start from root
directory of your current computerUse the here package to reference the project root, as here::here()
always starts at the top-level directory of a .Rproj
:
Help readers to navigate your document with numbered references and hyperlinks to entities like figures and tables.
Cross referencing steps:
fig-
or tbl-
.@fig-...
or @tbl-...
.The presence of the caption (Blue penguin
) and label (#fig-blue-penguin
) make this figure referenceable:
Markdown:
The presence of the caption (A few penguins
) and label (#tbl-penguins
) make this table referenceable:
Markdown:
Output:
See Table 1 for data on a few penguins.
species | island | bill_length_mm | bill_depth_mm | flipper_length_mm | body_mass_g | sex | year |
---|---|---|---|---|---|---|---|
Adelie | Torgersen | 39.1 | 18.7 | 181 | 3750 | male | 2007 |
Adelie | Torgersen | 39.5 | 17.4 | 186 | 3800 | female | 2007 |
Adelie | Torgersen | 40.3 | 18.0 | 195 | 3250 | female | 2007 |
Adelie | Torgersen | NA | NA | NA | NA | NA | 2007 |
Adelie | Torgersen | 36.7 | 19.3 | 193 | 3450 | female | 2007 |
Adelie | Torgersen | 39.3 | 20.6 | 190 | 3650 | male | 2007 |
Slides created via revealjs and Quarto: https://quarto.org/docs/presentations/revealjs/
Access slides as PDF on GitHub
All material is licensed under Creative Commons Attribution Share Alike 4.0 International.