-
Notifications
You must be signed in to change notification settings - Fork 7
/
Quarto_intro.qmd
208 lines (111 loc) · 10.4 KB
/
Quarto_intro.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
---
title: "Introduction to Quarto"
author: "Laura Lacher & James Fellows Yates"
date: "10/12/2023"
editor: visual
bibliography: references.bib
toc: true
---
In this introduction to quarto, you will be shown the basics in how to set up a website and a book. For more detailed information, I highly recommend checking out the [website](https://quarto.org) and also watch the [introduction tutorial](https://youtu.be/_f3latmOhew).
## Setting up
Quarto is the "next generation" of R Markdown and is usable on different tools.
{width="300"}
Here, we will describe how to set up your environment to use Quarto in **RStudio**, and VSCode.
Quarto in general is set up to be very intuitive and user friendly. And while it is possible to set up different documents simultaneously, those can also easily be set up to in just the way you need for whatever occasion. So, for either communicating your results to collaborators, discuss code with your supervisor, setting up a website or writing your paper, to just name some scenarios, quarto comes in quite handy. So, let's begin:
## RStudio
For this, you have to [download](https://posit.co/download/rstudio-desktop/) RStudio first. If you have done this already, we can get started.
### Getting started
First, we have to install the quarto package using the following command in our console:
`install.packages("quarto")`
Now we are ready to set up a quarto document.
For this we open a new project and select the quarto document we want to create. You can choose to set up a git repository as well. For practicality, I usually also tick the box visual markdown editor.
{width="300"}
The new project will look like this:
### Universal instructions
When setting up your document, quarto will always provide you with some presets. So first, we will have a look into the .qmd files, for they are handled the same way, regardless the format you are setting up (website, book, presentation, etc.).
#### Render & save
If we now click on render, we will be provided with the preview of our final version if the project in the viewer.
**Important: Do not mistake "save" with "render".** Just by saving, your document did not get rendered automatically, **unless** you tick the box "**Render on Save**". You have to tick that box on each .qmd file individually though.
{width="300"}
#### Visual and Source
If you have chosen the **Visual** option on your toolbar, the preview will mostly resemble your .qmd files. If you are more comfortable with the R markdown optics, you can switch to **Source.**
In the **Source** version, you can write up your document in LaTeX.
{width="400"}
#### .qmd files
Quarto will automatically provide you with two **.qmd files**, as well as a **.yml file**.
The .qmd files respond to the individual pages of your website or chapter of your book or pages of your presentation, etc. You can shape them individually or define the layout for all of them in the .yml file, to which we will get later.
In your .qmd files you also find a yaml at the top of your document, separated by
\-\--
\-\--
Within these, you can define the outline of .qmd file **individually**, starting with the page header. Other options, you might be using in the future are:
`author: Jessi Doe`
-\> will add an author underneath the header
`execute: echo: true`
-\> if \>true\<, code will be visible
`toc:true`
-\> if \>true\<, a table of content will be automatically added
`bibliography: your_references.bib`
-\> file or list of files for your references
It is crucial to stick to the spacing. Otherwise, an error will occur.
##### Insert
If you click `Insert`, you will realize, quarto provides you with a lot of options and shortcuts as well. So by just selecting on your chosen item to insert, it will be added to the document, while you are also provided with options on the appearance (in the case of figure/images or tables, etc). We will here have a brief look into how to work with **R code** and how to use the **reference** option.
##### R code
To add R code to your file, you select `Insert`, select `Code Cell` and choose the kind of code you want to insert. In this case, `R`. There are some things to keep in mind though.
Depending on how you have set up your .qmd file (or your .yml), your code will be visible or not on your website. To check your output, you can click the green arrow for the latest bit of code or the grey arrow above a bar to run the previous code.
{width="400"}
But in case there are some chunks of code, you do not want to show all the time, there are some nice sets.
So if we just load the library `tidyverse`, for example, the additional information regardless and it will be also visible on our website.
To avoid this, we can set up a code chunk, looking like this:
This will prevent the output of this code chunk to be depicted on your website, while the package is otherwise active and can be used in the following R code. This is, by the way, true for all R code and data sets you will use: they will be active in your document and can be used in different code chunks, once provided.
A code block included in your document could look like the following. Here I used the option
`code-fold: true` so the code can be extended. This option is only available in html though.
{width="400"}
##### References
Depending on which citation program you are using, quarto is able to connect to it ([Zotero](https://www.zotero.org) works, for example). So, when selecting to insert a `Citation`, you can choose to simply add a reference from your program.
Alternatively, you are provided with some options to choose from:
{width="200"}
In your source code and your website, a citation will be depicted as follows:
The citation will also automatically be added to a `references.bib` as well as to a `references.qmd` and is therefore available on your website on the page "References", which also will be created automatically.
### Render your document
When done with setting up your documents, you would like to have the actual output. Depending on the `format` you set in your .yml file, your output can be a `html`, `pdf`, `MS Word`, `OpenOffice`, or `ePUB` file. To create those, the terminal in your RStudio Project is used.
By using the command:\
`quarto render`
all formats you predefined in your .yml file will be rendered.
In case you are only interested in one format to be rendered, you can specify your command:
`quarto render -to pdf`
Your rendered document should now look like this:
### Quarto website
In the provided .qmd files, the index is also the first page of your website. As you might have noticed, quarto already sets up a navbar as well as a search function on your website.
{width="200"}
#### .yml files
While your .qmd files contain information about one page, the .yml file defines the overall looks of the website.
Here, you can define the type of your project (in this case a website), you can change the name of the website (`Title`), define your navbar (which shall be your landing page and in what order your pages shall be set up) or the overall appearance of your website in general (`theme`, `css`, `toc`, `backgroundcolor`, etc.). For different styles and layouts, check out the quarto [website](https://quarto.org/docs/reference/formats/html.html) again.
{width="200"}
### Quarto book
The setup of the .yml file in a quarto book is slightly different than that of the website. So here are some general remarks about them.
#### .yml files
We see, for example, that instead of a navbar, we find `chapters`. Those will appear in the listed order in your book.
We also already get provided with a `bibliography` and the responding .bib file. If you have other .bib files, those can be included in your references, by just adding them to `bibliography`.
{width="200"}
\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
With this, you should at least have some ideas on how you can use quarto in your daily work routine. Happy coding and please feel free to contact me for any remarks or questions. I am happy to try and help.
## VSCode
Much of the concepts as described in the RStudio tutorial above apply equally well to using Quarto in VSCode, just with a different interface to execute them.
Here we will describe how to set up VSCode and Quarto, and how to preview and render Quarto objects within the VSCode interface.
To understand about more about the details of which files to edit etc., please see the RStudio description above.
### Getting Started
1. Install the Quarto CLI tool for your operating system from the [Quarto Website](https://quarto.org/docs/get-started/)
2. Install the [VSCode Quarto extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto)
### Using Quarto
The basic workflow is as follows:
1. Create or modify `.qmd` objects etc as described above in the Rstudio section about [Quarto markdown files](#qmd-files)
2. Within VSCode, make sure you've opened it in the repository containing all the files
3. Press <kdb>ctrl</kbd> + <kbd>shift</kbd> + <kbd>p</kbd> to bring up your command palette
1. To preview a local 'live' version of HTML or website versions, you can type `Quarto: preview`. To close the live preview, press <kbd>ctrl</kbd>+<kbd>c</kbd> in the VSCode terminal.
2. To render all the files e.g. final HTML and/or PDF versions, you can type `Quarto: Render Project`, where you will be given different options depending on the formats defined in the `_quarto.yml` file.
For further VSCode integrations, just type `Quarto:` into your command palette and explore all the options.