ETC5523: Communicating with Data

Data storytelling on the web

Lecturer: Emi Tanaka

Department of Econometrics and Business Statistics



Aim

  • Understand a website structure and its difference to a webpage
  • Learn how to use Quarto
  • Adopt reproducible workflows using Quarto
  • Host web content using either Quarto Pub, GitHub Pages or Netlify

Why

  • Communication on the web is increasingly common
  • There are challenges to streamline reproducible data analysis on the web

Rmd R Markdown

(Assumed knowledge from ETC5513)

R Markdown system

Benefits

  • Better reproducibility for analytical results via R
  • Change output document type easily (thanks to Pandoc)
  • Active maintenance and development by RStudio a.k.a. Posit team

qmd Quarto

(multi-language, next generation version of R Markdown)

Note: this is developed by RStudio (or Posit from October 2022) team.

Quarto system

Changes

  • The reproducible workflow is no longer dependant on R
  • Better multi-language support (e.g. Python, Julia, JavaScript, R, etc) and multi-engine support (e.g. Jupyter, Knitr, Observable)
  • Consistency in systems across all formats (e.g. layouts, cross references)
  • Some specifications for YAML and chunk options

Overall syntax comparison

Rmd

---
title: "My document"
output:
  html_document:
    toc: true
    css: styles.css
---

```{r, warning = FALSE, message = FALSE}
knitr::opts_chunk$set(echo = FALSE,
                      fig.width = 8, 
                      fig.height = 6)
library(tidyverse)
```

Qmd

---
title: "My document"
execute: 
  echo: false
format:
  html:
    toc: true
    css: styles.css
    fig-width: 8
    fig-height: 6
    html-math-method: katex 
---

```{r}
#| warning: false
#| message: false
library(tidyverse)
```

Do we use Rmd or Qmd?

  • If your computation uses only R, Rmd is completely fine.
  • In this unit, we will be using Quarto for making:
    • websites (including blogs) and
    • presentation slides.

How to use Quarto

  • Quarto is quite NEW – v1 was released only on 20th July 2022!

  • The best documentaton is at https://quarto.org/

Making Websites with Quarto

Webpage vs. Website

What is the difference?

  • A webpage is a single document written in HTML.
  • While a website is a collection of webpages where it usually share a common navigation bar (or tab), and possibly a common footer.

Web server directory index

Getting started with Quarto blog

Using RStudio IDE

File > New Project > New Directory > Quarto Blog

Command line

Run in the terminal:

quarto create-project myblog --type website:blog

This creates a basic file structure in the myblog directory.

Quarto blog template

Quarto blog structure

├── _quarto.yml
├── index.qmd
├── about.qmd
├── profile.jpg
├── styles.css
└── posts
    ├── _metadata.yml
    ├── welcome
    │   ├── thumbnail.jpg
    │   └── index.qmd
    └── post-with-code
        ├── image.jpg
        └── index.qmd

Quarto workflow

  • For a live preview of the website (when developing):
quarto preview
  • For rendering the website (default folder is _site):
quarto render

_quarto.yml

project:
  type: website

website:
  title: "myblog"
  navbar:
    right:
      - about.qmd
      - icon: github
        href: https://github.com/
      - icon: twitter
        href: https://twitter.com
format:
  html:
    theme: cosmo
    css: styles.css

index.qmd


---
title: "myblog"
listing:
  contents: posts
  sort: "date desc"
  type: default
  categories: true
  sort-ui: false
  filter-ui: false
page-layout: full
title-block-banner: true
---

Publishing websites

Web hosting

Sharing on the web with Quarto Pub

quarto publish quarto-pub
  • The website will be published at https://username.quarto.pub/mysite/ where
    • username is your Quarto Pub username
    • mysite is the site name

Sharing on the web with GitHub Pages

usethis::use_git()
usethis::use_github() # or manually link with your local folder
  1. Push your directory to your Github repo, say mysite.
  2. Go to your GitHub repo settings and enable “GitHub Pages”.
  3. Your website will be available with url: http://username.github.io/mysite

Note: it may take 10 minutes or so to render the first time.

Alternatively use

quarto publish gh-pages

Sharing on the web with Netlify

  1. Go to https://app.netlify.com and log in
  2. Drag and drop your site folder which contains the index.html to:
  1. Do go to Site settings > Change site name for a more sensible domain name.

Alternatively use

quarto publish netlify

Week 4 Lesson

Summary

  • We looked at a website structure
  • We built a website using the Quarto system
  • We learnt how to host websites using Quarto Pub, GitHub Pages or Netlify

Resources

ETC5523 Week 4