Building a Personal Website using Quarto

.title[
# Building a Personal Website using Quarto
]
.author[
### <br>Kuan Liu<br> <br> Guest lecture - R workshop
]
.date[
### <br>Nov 24, 2024
]

---

## Front matters

-  For this workshop we assume you know R and Rstudio.

-  In this tutorial, we will learn how to build a simple personal website using Quarto and hosting the page on [GitHub](https://github.com/)

---

## What is Quarto?

.purple[.bold[Quarto]] is an open-source scientific and technical publishing system built on [Pandoc](https://pandoc.org/)

Publish high-quality .black[articles], .red[reports], .blue[presentations], .green[websites], .yello[blogs], and .orange[books] in HTML, PDF, MS Word, ePub, and more.

.purple[.bold[Quarto]] can author documents in plain text formats (**rmarkdown**, **markdown**) or mixed formats (**Jupyter** notebook) - .bold[more than just Rmarkdown!]

---

## What is Quarto?

![](https://quarto.org/docs/get-started/hello/images/rstudio-source-visual.png)

---

## List of Quarto formats

-  Basic documents in html, pdf, docx
-  Presentations in beamer, pptx, and revealjs (html slides)
-  .blue[.bold[Websites & Blogs]] in [Quarto Website](https://quarto.org/docs/websites/) and [Quarto Blogs](https://quarto.org/docs/websites/website-blog.html)

---

## Quarto > RMarkdown

**Quarto is a one-stop-shop that renders multiple output formats!**

![](https://mine-cetinkaya-rundel.github.io/quarto-tip-a-day/posts/19-gallery/featured.gif)

---

# .black[**Building Websites with Quarto**]

---

## Why not WordPress, Medium etc

-  **Minimum Rmarkdown support**

-  no ads, no login/password, no cost!

-  fast building!

---

## Quarto websites

**Convenient:** Documents published as part of a website share navigational elements, rendering options, and visual style.

**Features:** Website navigation through a global navbar, a sidebar with links, or both. You can also enable full text search for websites.

Example website: https://kuan-liu.github.io/biostat3/

**Host:** can be published to a wide variety of destinations including .purple[**GitHub Pages**], .green[**Netlify**], .blue[**RStudio Connect**], etc.

---
## Getting started

-  Create a website

```
quarto create-project MySiteName --type website

```

-  create a blog

```
quarto create-project MyBlogName --type website:blog

```

-  or use RStudio \> New Project \> New Quarto Blog

---

## Try this - create Quarto website project

-  Create a new RStudio project and select a new directory and Quarto website

-  specify directory name with your GitHub account name plus **.github.io**,  e.g., Kuan-Liu.github.io
    
-  Explore the directory

---

## Navigation & Structure

-  `_quarto.yml`, website configuration file
    -  provides website options such as website theme, navigation bar.
    
-  index.qmd, home page of the website

-  about.qmd, the about page of the website

-  styles.css, Custom CSS for website (for advanced coder)

---

## Rendering posts and building webiste

-   On a specific post, Render with RStudio \> Render
-   Build tab \> Render/Preview Website (try)

These will preview the entire website

-  "Freeze" is a feature to specify which file you would like to render at each built (fast & efficient building).

```
execute:
  freeze: auto  # re-render only when source changes
  
```
-  Add `freeze: auto` to the _quato.yml file

---

## Themes

-  My favourite two new themes: Zephyr and Quartz
  -  A list of build-in themes: https://quarto.org/docs/websites/website-blog.html#themes

-  To change theme, modify the bottom of your website's `_quarto.yml`

``` yaml
format:
  html:
    theme: Zephyr
```

---

## About page templates

-  list of themes: https://quarto.org/docs/websites/website-about.html

.pull-left[
### jolla
<img src="https://quarto.org/docs/websites/images/about-jolla.png" width="400px"/>
]

.pull-right[
### trestles
<img src="https://quarto.org/docs/websites/images/about-trestles.png" width="400px"/>
]

---

## Try this - customize the about page

-  create a subfolder in your working directory called "images" and put a thumbnail photo in this folder (for example, HDWG.jpg).

-  now updating the about page title section with

``` yaml
about:
  template: jolla
  image: images/HDWG.jpg
  links:
    - icon: twitter
      text: twitter
      href: https://twitter.com/
    - icon: github
      text: Github
      href: https://github.com/
```

---
## Home page

-  The home (landing) page for this website by default is generated following the `index.qmd` file

-  We might want to feature about page as the landing page
    -  simply rename the qmd files about.qmd to index.qmd 
    -  and rename index.qmd to anther tab of your website, for example publication or research

---

## Try this - Adding icons to social account

-  You can add links to GitHub, Twitter, Google Scholar on the navigation bar with icon by updating the config file, `_quarto.yml`

``` yaml
  navbar:
    right:
      - href: index.qmd
        text: Home
      - icon: github
        href: https://github.com/my_user_name
      - icon: twitter
        href: https://twitter.com/my_user_name
```
---

## Blog posts

-  you can add a quarto page to host blog posts by creating a blog.qmd file where you will display your blog posts in a listing.

![](https://rstudio-conf-2022.github.io/get-started-quarto/materials/images/mockup-blog.png)
---

## Listing

-  There are three types of listing displays: default, table, and grid

-  Grid

![](https://quarto.org/docs/websites/images/listing-grid.png)

]

![](https://quarto.org/docs/websites/images/listing-table.png)

]
---

## Try this - creating a blog post

1.  create blog.qmd and specify in the title section

```---
title: my blogs
listing:
  contents: posts
  sort: "date desc"
  type: default
  categories: true
---
```

2.  create a sub folder name it "posts", under "posts" create another sub folder name it "blog1"

---
## Writing a post

1.  inside blog1 folder try Blank File \> Quarto document and name it index.qmd ([example](https://kuan-liu.github.io/blog.html)). 
    -  **This index.qmd will host content of your blog!**

2.  specify in the title section of blog1/index.qmd

```---
title: "My first post with R"
description: "you can post a summary description here"
author: "Kuan"
date: "11/20/2023"
categories:
  - R code
---
```

---

## Publishing - GitHub

-  Use [GitHub Pages](https://quarto.org/docs/publishing/github-pages.html) when the source code for your document or site is hosted on GitHub repo.
-  make sure to render your site (html files) in the docs folder
  -  in _quarto.yml specify `output-dir: docs`

-  **Try this:** 
    1.  Build your website and push to GitHub repo **github_account.github.io**
    2.  go to settings of the repo and select page. Specify Branch master and /docs and save!
    3.  Your site should be live at https://github_account.github.io.

---

## Try this - publishing your website on GitHub

-  You can folk or download codes to build the [template Quarto website](https://kuan-liu.github.io/) I made for this tutorial at **https://github.com/Kuan-Liu/Kuan-Liu.github.io**.

---
class: ut-pantone_yellow

# .black[**Building Websites with blogdown**]

---

## What is blogdown?

-  An R package for building website using R Markdown and [Hugo](https://gohugo.io/)
    -  building website via Hugo using Rmarkdown

-  Hugo
    -  no cost, open-source, and easy to install
    -  tons of features for fancy customization if you are familiar with css (Cascading Style Sheets)
    -  example website: https://www.kuan-liu.com/
    
-  blogdown book: https://bookdown.org/yihui/blogdown/

---

## Getting started

-  Be sure that you have installed the **blogdown** package

``` r
install.packages("blogdown")
blogdown::install_hugo(version="0.86.0")
blogdown::hugo_version()
# if you have multiple version of hugo, you can specify which version to use;
# options(blogdown.hugo.version = '0.86.0')
```

-  list of Hugo themes: https://themes.gohugo.io/
    -  for my personal website I used the [hello-friend-ng](https://themes.gohugo.io/themes/hugo-theme-hello-friend-ng/) theme
    -  go to https://themes.gohugo.io/ and take a quick look at all the amazing Hugo theme templates

---

## Try this - create a new blogdown project

.pull.left[

-  create a new project, select website using blogdown, specify Hugo theme `hugo-apero/hugo-apero`

]

.pull.right[

<img src="assets\blogdown1.png" alt="drawing" width="500"/>
]
---
class: left, ut-pantone_lime

## Try this - building website

-  explore the project structure

-  try Knit the website

-  subfolder *content* contents all markdown files or rmarkdown files for your website

---

## Publishing on Netlify

-  create and upload repo on GitHub via GitHub desktop

-  log in to your netlify account via GitHub!

-  select add new site \> import an existing project \> connect to GitHub \> select repo

-  update domains names

---
class: left, ut-pantone_lime

## Live demo - pulishing website on Netlify

---

## Acknowledgement

- "Permanent link" to the slides at https://kuan-liu.github.io/Quarto_website_workshop/

- Credit: This template and tutorial is created based on [Tom Mock](https://rstudio-conf-2022.github.io/get-started-quarto/)

---

background-image: url("https://arthistory.utoronto.ca/sites/arthistory.utoronto.ca/files/styles/slider_large_img/public/front_carousel/HH01.jpg?itok=ukdDyPF0")
background-position: bottom
background-size: contain

## Thank you!

-  Materials for this workshop
    -  [online slides](https://kuan-liu.github.io/Quarto_website_workshop/#1)
    -  [Quarto template personal page repo](https://github.com/Kuan-Liu/Kuan-Liu.github.io)
    -  [Quarto template personal page](https://kuan-liu.github.io/)