ETC5523: Communicating with Data

Data storytelling on the web

Lecturer: Michael Lydeamore

Department of Econometrics and Business Statistics

michael.lydeamore@monash.edu
Week 4
cwd.numbat.space

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

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)

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

index.html is a special reserved name for the “index” page
If you go to https://cwd.numbat.space/, this in fact is loading https://cwd.numbat.space/index.html
Any other file name and folder structure requires you to append it to the domain or subdomain, e.g. https://cwd.numbat.space/lectures/lecture-00.html

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 (demo)

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

Go to https://quartopub.com/ and log in
In the terminal, run

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

Push your directory to your Github repo, say mysite.
Go to your GitHub repo settings and enable “GitHub Pages”.
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

Go to https://app.netlify.com and log in
Drag and drop your site folder which contains the index.html to:

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