Lecture 2

Getting Started with Quarto

Byeong-Hak Choe
bchoe@geneseo.edu

SUNY Geneseo

January 27, 2025

Getting Started with Quarto

Building a Personal Website on GitHub

Let’s Practice Markdown!

  • Quarto, Jupyter Notebook, and GitHub-based Discussion Boards use markdown as its underlying document syntax.

  • Let’s do Classwork 2.

Getting Started with Quarto

YAML

  • An YAML (yet another markup language) header surrounded by ---.
    • It is commonly used for document configuration (e.g., title, author, date, style, …).
  • Chunks of Python/R code surrounded by three backticks, \(\text{```}\).

Getting Started with Quarto

Knitting / Rendering

  • When we knit the document, Quarto sends the .qmd file to jupyter/knitr, which executes all of the code chunks and creates a new markdown (.md) document which includes the code and its output.

  • The markdown file (*.md) generated by jupyter/knitr is then processed by pandoc, which is responsible for creating the output file.

Getting Started with Quarto

Markdown, Quarto, and HTML

  • The very original version of Markdown was invented mainly to write HTML content more easily.
    • For example, - SOME_TEXT in “.md” is equivalent to <ul><li> SOME_TEXT </li> in ”.html”
  • Pandoc makes it possible to convert a Markdown document to a large variety of output formats, such as HTML.

Getting Started with Quarto and HTML

Markdown, Quarto, and HTML

---
title: "Habits"
author: YOUR_NAME
date: January 27, 2025
format: 
  html
---

  • To create an HTML document from Quarto, we specify the html output format in the YAML metadata of our document.

    • By default, format: html is set.

  • In RStudio, we can create a new Quarto file from the menu, File -> New File -> Quarto Document.

  • Open an empty Quarto file.

    • Type the above YAML metadata to the empty Quarto file.

Getting Started with Quarto

Quarto Basics

---
title: 
subtitle: 
author: 
date: last-modified

format: 
  html:
  
execute: 
  echo: true
  eval: true
---

  • Download the Quarto file, danl-310-quarto-r.qmd from Brightspace, and open it from RStudio.

  • This syntax is part of YAML metadata in danl-310-quarto-r.qmd.

    • In YAML, indentation really matters!
    • tab (or four spaces) defines a level in YAML.

Managing a Website with Quarto (and Jupyter Notebook)

Quarto Websites

---
project:
  type: website

website:
  title: "YOUR NAME"
  navbar:
    left:
      - text: Project
        href: project.qmd
      - text: Blog
        href: blog-listing.qmd
format:
  html:
    theme: cosmo
    css: styles.css
    toc: false
---

  • The _quarto.yml file configures the website settings.

  • Indentation matters!

  • In RStudio, open the project USERNAME.github.io.Rporj.
    1. Click Project: (None) at the top-right corner.
    2. Click USERNAME.github.io.Rporj.
  • _quarto.yml configures a website, and provides various options for HTML documents within the website.

Quarto Websites

Custom CSS

  • Cascading Style Sheets (CSS) is used to format the layout of a webpage (color, font, text size, background, display, etc.).
    • HTML will format the architecture of the house.
    • CSS will be the carpet and walls to decorate the house.
    • JavaScript adds interactive elements in the house, such as opening doors and lighting.
  • We are not front-end web developers.
    • We will not cover the use of CSS and JavaScript.

Quarto Websites

Rendering

  • The Render button (command/Ctrl + shift + K) renders a single Quarto file.

  • quarto render from Terminal renders all Quarto/Jupyter Notebook files in your local working directory:

quarto render
  • We should use quarto render when we have changes in _quarto.yml.
  • Edit _quarto.yml and *.qmd only from your local laptop.
    • Do not make any change in those files from the GitHub repo webpage.

Quarto Websites

Appearance and Style

  • theme specifies the Bootstrap theme to use for the page (themes are drawn from the Bootswatch theme library).
    • Valid themes include default, bootstrap, cerulean, cosmo, darkly, flatly, journal, lumen, paper, readable, sandstone, simplex, spacelab, united, and yeti.
  • highlight-style specifies the code highlighting style.
    • Supported styles include default, tango, pygments, kate, monochrome, espresso, zenburn, haddock, breezedark, and textmate.

Quarto Websites

About

Quarto Websites

Icons and Emojis

Quarto Websites

left:
- text: Project
  href: project.qmd
- text: Blog
  href: blog-listing.qmd
- text: Homeowrk
  href: hw.qmd
  • We can add a new page to the website through navbar in _quarto.yml

Quarto Websites

left:
  - text: "Projects"
    menu:
      - project_1.qmd
      - project_2.qmd

Quarto Websites

Colors

Quarto Website Basics