tutorial.qmd

---
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: fork and clone the workshop template repository

Go to the [template-02quarto repository](https://github.com/rladies-zurich/template-02quarto) available on R-Ladies Zurich repository.

![](resources/0_clone_template.png){width=85% fig-align="center"}

**Fork** the repository (so that you have your own copy). 

Then, clone the repository by clicking on **Code**, copy the link;

In RStudio, **create a new project**, choose **Version Control**:

![](resources/1_vc_project_git.png){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.

![](resources/1_vc_project_clone.png){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.

![](resources/2_index_1.png){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!

![](resources/2_index_2.png){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.

:::

![](resources/2_minimal_site.png){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.

![](resources/3_commit.png){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.

![](resources/3_config_ghp.png){width=85% fig-align="center"}


This should take less than 1 minute. Meanwhile, you can click around and check GitHub Action and deployment status. 

![](resources/3_action.png){width=85% fig-align="center"}

![](resources/3_deploy.png){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:

```
![caption](path_to_figure.png) {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: 

![](resources/4_rcode.png){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/)