forked from rladies-zurich/workshop-02quarto
-
Notifications
You must be signed in to change notification settings - Fork 0
/
tutorial.qmd
388 lines (213 loc) · 13 KB
/
tutorial.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
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
---
title: "Tutorial: a step-by-step walkthrough"
author: "Chi Zhang"
date: 2023-10-17
format:
html:
toc: true
toc-depth: 3
linestretch: 1.7
---
This tutorial outlines a minimal workflow so that you can build your own quarto website. For a more complete guide, please refer to the [official quarto documentation](https://quarto.org/).
::: callout-note
## This workflow requires:
* GitHub account to set up a public repository
* RStudio (after 2022, better after 2023)
* Quarto (download [here](https://quarto.org/docs/get-started/))
:::
::: callout-note
## Workshop material
You can find the workshop material from the GitHub repository of [R-Ladies Zürich](https://github.com/rladies-zurich).
* Workshop [website](https://andreaczhang.github.io/workshop-02quarto/) and [repo](https://github.com/rladies-zurich/workshop-02quarto)
* Workshop reveal.js slides [link](https://andreaczhang.github.io/slides-02quarto/)
* Quarto website template [template-02quarto](https://github.com/rladies-zurich/template-02quarto) for you to download and modify
The source repository and slides can be found in Chi's personal GitHub repositories.
:::
## 1. Set up a version controlled quarto project
There are a few ways to do this.
* **Option 1 is recommended for the workshop today**; it contains a minimal website page with customized color palette;
* Option 2 is for those who are familiar with linking GitHub with RStudio, and want to create their own quarto project. Feel free to explore!
### Option 1: clone the workshop template repository
Go to the [template-02quarto repository](https://github.com/rladies-zurich/template-02quarto) available on R-Ladies Zurich repository.
{width=85% fig-align="center"}
Clone the repository by clicking on **Code**, copy the link;
In RStudio, **create a new project**, choose **Version Control**:
{width=65% fig-align="center"}
Paste the link, and enter a name for your project. Create. This step copies content to your local machine, and inside your Rstudio you should see a tab named Git.
{width=65% fig-align="center"}
### Option 2: create your own public repository
This option is for those who are familiar with using GitHub and version controlled R project, and want to make a quarto website from scratch. (You are welcome to download the files directly from the template repo into your own!)
* Create a new **public** repository
* Clone the repository to your local machine
* Open a new project in Rstudio, choose version control
* Paste link, name your repo.
This will create an empty version controlled Rproject. After this, you can choose to download the files from the template repository directly; or create your own quarto files.
::: {.callout-tip collapse="true"}
## How do you know the repository is correctly set up?
You can try to modify the `README.md` locally, then commit and push to remote (online repository). Refresh the webpage, if you see the remote repository is synced, that means the version control works fine.
:::
## 2. Build the project
Now you see a few files that have been downloaded in the folder where you `Rproject` is located. Before going into more details, let's build your first webpage to see what happens!
Locate `index.qmd`, open it.
{width=65% fig-align="center"}
You should have a button **render** when you open the `index.qmd` file. Click on **render**. Do you see an HTML page in the *Viewer* panel?
If you do, that's great! We're ready for the next step!
{width=75% fig-align="center"}
### 2.1 Structure of a new quarto project
Let's understand what makes a minimal quarto website. These are the **three most important files** that you downloaded from the template repository:
* `_quarto.yml` stores the meta-data for the website, such as structure, layout and other information;
* `index.qmd` is your homepage;
* `styles.scss` provides a customized appearance of the website.
You've also downloaded `.gitignore` and a `LICENSE`. They are important, but not essential when building a website per se.
::: {.callout-tip collapse="true"}
## Customized R Ladies style
Strictly speaking, you *do not* need a `style.css`/`style.scss` to build a minimal quarto website. Quarto will use a default `cosmo` style when you don't specify anything. We'll see how to modify the theme in a few moments.
:::
{width=85% fig-align="center"}
### 2.2 Authoring
Inside the `index.qmd`, you will see some information at the top of the page. This is the `YAML` header that specifies some basic information about this document.
For example, `toc` means **table of content**. By `toc: true` a list of sub-titles appear to the right of the page.
In addition, you can specify information such as **author** and **date**.
```
---
title: "Zero to Quarto Workshop"
subtitle: "Build your first quarto website (or something other cool things!)"
format:
html:
toc: true
toc-depth: 2
---
```
Below the `YAML` header, you can modify some text in [markdown](https://quarto.org/docs/authoring/markdown-basics.html) style.
### 2.3 Configure the quarto project
To prepare for [publishing the website with GitHub Pages](https://quarto.org/docs/publishing/github-pages.html), we need to do a few things in the quarto project before pushing all the files to GitHub.
In addition to GitHub Pages, there are also [other ways](https://quarto.org/docs/publishing/) to publish the website. Feel free to explore!
#### 2.3.1 output-dir
In `_quarto.yml`, change (or double check that) the project configuration to use `docs` as the `output-dir`:
```
project:
type: website
output-dir: docs
```
What this does is that when you click **render**, the built website with all the HTML files will be placed and updated in the `docs` folder. This step is essential when we configure GH pages setting to deploy from `docs` folder.
::: {.callout-tip collapse="true"}
## Set output-dir to docs
In the `_quarto.yml` you downloaded from the workshop template, it already specified the `output-dir: doc`.
When you build a website from scratch, by default, this is usually not the case. You'd need to add this line yourself.
:::
#### 2.3.2 nojekyll
Add `.nojekyll` to the root of the repository: it is same location where `_quarto.yml` is.
You can do this by (in *Terminal*)
```
touch .nojekyll
```
::: {.callout-tip collapse="true"}
## Find *Terminal*
If you don't have *Terminal* panel next to *Console*, it can be opened by Tools > Terminal > New terminal.
Alternatively, you can also use your favorite command line software to navigate to the project and add `.nojekyll` there.
:::
Finally, commit all the files, and push everything to your remote repository on GitHub repository.
{width=65% fig-align="center"}
## 3. Configure GitHub pages, test deployment
::: {.callout-tip}
When you are more experienced, you can add more content until you're happy *before* configuring the GH pages and test the website deployment. Yes, you can swap step 3 and 4 in this tutorial.
I personally prefer to test the deployment early on to make sure it works!
:::
On GitHub: go to **Settings > Pages > Build and deployment**, publish from `docs` of the `main` branch. Save.
{width=85% fig-align="center"}
This should take less than 1 minute. Meanwhile, you can click around and check GitHub Action and deployment status.
{width=85% fig-align="center"}
{width=85% fig-align="center"}
After the deployment is successful, go to `view deployment`, and a successful website should be published.
A URL should appear to tell you where the website is: it usually takes the form of `https://your_username.github.io/your_reponame/`
It is good practice to save it on the page where your repository is located, to the top right. This way you can find it easily in the future!
## 4. Add content
Now this is really where you can be creative. There are so many things you can change; but let's focus on some basics first.
### Site navigation and new pages
What we have here is a very minimal one-page website. It is easy to add more pages; the question is, where to?
Quarto offers a few options, and all of them can be specified in `_quarto.yml` file.
This is how the navigation style of our [workshop webpage](https://andreaczhang.github.io/workshop-02quarto/) is specified (under `navbar`). Feel free to check the source code for this YAML file [here](https://github.com/andreaczhang/workshop-02quarto/blob/main/_quarto.yml).
* `left` and `right` specifies the location on the navigation bar, where the tabs should appear;
* `href` is the link of the document or URL to the page. It can be a quarto document in the same directory or sub-directory, but can also be a URL for any existing webpage online;
* `text` is what the tab is named;
* `icon` provides the GitHub icon rather than text.
```
website:
page-navigation: true
title: "Zero to Quarto Workshop"
navbar:
left:
- href: index.qmd
text: Home
- href: setup.qmd
text: Set up
- href: tutorial.qmd
text: Tutorial
- href: slides.qmd
text: Slides
right:
- icon: github
href: https://github.com/andreaczhang/workshop-02quarto
```
For more complex website such as courses or workshops, you might need **other types of navigation** to present information. Read more [here](https://quarto.org/docs/websites/website-navigation.html) to find out how you can do it.
### Theme
The appearance of the workshop template is inspired by the [R Ladies](https://rladies.org) colors. If you want to use a preset provided by quarto, it is perfectly fine - they look nice and professional already.
To modify themes, in `_quarto.yml`, instead of providing `styles.scss` file, use the theme name you prefer: `cosmo`, `zephyr` are good places to start.
For more themes, check [here](https://quarto.org/docs/output-formats/html-themes.html).
```
format:
html:
theme: cosmo
```
Alternatively, feel free to modify the `styles.scss` to test different color palettes and font styles. Go wild!
:::{.callout-tip collapse="true"}
## Custom themes
Quarto has provided some [guide](https://quarto.org/docs/output-formats/html-themes.html#custom-themes) on how to make custom themes. However, the easiest way to get started is to find an existing style you like, and try to modify it.
:::
### Figures and tables
It is straightforward to include images in the website. One way to include a local figure in an article (such as blogpost) goes like this:
```
 {width=85% fig-align="center"}
```
To make a simple table, you can directly enter the table in the quarto document:
```
| Default | Left | Right | Center |
|---------|:-----|------:|:------:|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
: Table name
```
| Default | Left | Right | Center |
|---------|:-----|------:|:------:|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
: Table name
Read about how to work on [figures](https://quarto.org/docs/authoring/figures.html) and [tables](https://quarto.org/docs/authoring/tables.html).
### Code chunks
Use a code fence (3 backticks) with the language you wish to run the code:
{width=65% fig-align="center"}
```{r}
#| label: fig-airquality
#| fig-cap: "Temperature and ozone level."
#| warning: false
library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) +
geom_point() +
geom_smooth(method = "loess")
```
Depending on your needs, you may want to hide the code and/or not execute the code. Learn how to work on code in [this chapter](https://quarto.org/docs/computations/r.html) of the quarto doc.
### (Optional) Add interactivity
The latest quarto version and extension supports running R scripts interactively from a web-browser: i.e. no local execution of the R code.
I have a blogpost on this topic, [read here](https://andreaczhang.github.io/blog/technotes_20231001_qt_webr/). However, be aware that this technology is yet to be improved, so what you know today about `webr` might not work next month...
# Summary and resources
### Workflow
Today we went through 4 steps:
* set a version controlled quarto project
* build the project locally, configure necessary parts (`output-dir` and `.nojekyll`)
* push to GitHub, configure GH pages setting
* add more content
It takes a few try to make a website that you need. But this is a good start! One day you will make your own portfolio, or a course website that truly belongs to you!
### Resources
[Quarto Gallery](https://quarto.org/docs/gallery/) shows a nice and inspiring collection of the types of projects you can create. Make sure you check them out!
* Create [website](https://quarto.org/docs/websites/) on official quarto documentation
* Create [book](https://quarto.org/docs/books/), [presentation](https://quarto.org/docs/presentations/)