From Zero to Website with Quarto

DSLC 2024

Charlotte Wickham

Getting set up

Make sure you’ve:

1. Joined the Posit Cloud workspace: Link in Slack

2. Started the “Website” project (look under “Content” tab)

3. Created a Quarto Pub account: https://quartopub.com/sign-up

Code of Conduct

Welcome!

Hello, I’m Charlotte Wickham:

• Developer Educator at Posit
• In Corvallis, Oregon
• Longtime RMarkdown user, now Quarto user

TAs: Derek Sollberger, Priyanka Gagneja, Federica Gazzeloni, and Collin Berke

Your Turn

Introduce yourself to your breakout room:

• Name
• Location
• Something you hope to get out of the workshop

Check you are all set up

5 mins

Outline

Goal: You create a website with Quarto

1. Don’t start from scratch
2. Add pages and customize navigation
3. Make the style your own
4. Publish
5. Use listings for “lists” of content

What to expect

My turns: I’ll use slides, and live code to demonstrate ideas.

Your Turns: You practice what you’ve just seen in breakout rooms where TAs can help.

Ask questions:

• in zoom chat
• in breakout room
• in Slack (I’ll answer after the workshop)

1. Don’t start from scratch

Before the workshop…

DON’T RUN: Using a template

This is what did before the workshop to get the template:

Terminal

quarto use template cwickham/minimal-website

Demo: Exploring index.qmd

• Render/preview index.qmd. It becomes index.html, your homepage.

• Regular Quarto document with:

  • YAML Header
  • Content, possibly including code cells

• Workflow: Edit, render/preview

• Uses an about template: https://quarto.org/docs/websites/website-about.html

• Other templates: jolla, trestles, solana, marquee, or broadside

Your Turn

Edit index.qmd:

• Change the title and subtitle
• Try a different template: jolla, trestles, solana, marquee, or broadside
• Edit, add, or remove items in links
• Challenge: Use a different image, and edit image-alt

Spare time? Edit the content of the page

8 mins

Demo: Use a different image

1. Move new image into project
2. Replace path
3. Edit image-alt

Paths in a .qmd are relative to the location of the .qmd

2. Add pages and customize navigation

Demo: Add a page

1. New Quarto Document: projects.qmd

   projects.qmd

   ---
   title: Projects
   ---
   
   Some projects I've worked on:

2. File path becomes URL path: { site url }/projects.html

Demo: Add navigation

_quarto.yml: configuration file

project:
  type: website

Identifies this as a Quarto website

website:
  navbar:
    right: 
      - projects.qmd

Controls navigation and other website settings

More file path examples

File path becomes URL path

File location

demo.qmd

talks/index.qmd

data/air-quality.csv

URL

{ site url }/demo.html

{ site url }/talks/

{ site url }/data/air-quality.csv

Your Turn

1. Add a page
2. Add a link to the page in the navigation
3. Skim https://quarto.org/docs/websites/website-navigation.html. What other types of navigation are available?

Spare time: Add content to the page

8 mins

Demo: Navigation

1. Put items on left
2. Switch to a sidebar and back again
3. Edit tools

https://quarto.org/docs/websites/website-navigation.html

3. Make the style your own

Option 1: Use built-in theme

_quarto.yml

format:
  html:
    theme: [vapor]

List of available themes: https://quarto.org/docs/output-formats/html-themes.html

Option 2: Edit styles in styles.scss

_quarto.yml

format:
  html:
    theme: [cosmo, styles.scss]

styles.scss

/*-- scss:defaults --*/

$body-bg: white; 
$body-color: #333333;
$primary: #333333;

// Common variables to add a bit more color: 
// $link-color, $headings-color, $navbar-bg
$navbar-bg: #311e47;
$headings-color: #311e47;

4. Publish

Demo: Use quarto publish

Terminal

quarto publish quarto-pub

Other venues: gh-pages, netlify, connect, posit-cloud

Updates? Re-run quarto publish

Your Turn

1. Publish your site to Quarto Pub:

   Terminal

   quarto publish quarto-pub

2. Experiment with different built-in themes.

3. Publish an update to Quarto Pub

4. Challenge: Edit some of the hex colors in styles.scss

5. Use listings for lists of content

A listing is…

• an automatically generated list of content
• styled via a template, (built-in type, or custom template)
• can be included on any page

Use listings for …

contents can be a YAML file

talks/index.qmd

---
title: Talks
listing:
  contents: talks.yml
  type: table
  fields: [title, venue, date]
---

talks/talks.yml

- title: "Quarto: Reproducible Publishing"
  date: 2024-03-01
  venue: Oakridge National Lab
  path: https://github.com/cwickham/oakridge
- title: What's New in Quarto?
  date: 2023-09-01
  venue: "`posit::conf(2023)`"
  path: https://youtu.be/WR08GESib9Y?si=vTxco6_yuEDV8TBC
- title: This Month I Learned...
  date: 2021-04-01
  venue: Rladies Washington D.C., via Zoom 
  path: https://cwickham.github.io/this-month-I-learned/#1

Wrap Up

Quarto Websites

A minimal website only needs two files:

_quarto.yml

project: 
  type: website

index.qmd

---
title: My homepage
---

• Add pages by adding Quarto documents
• Control navigation, website settings, theming etc. in _quarto.yml

Explore docs at: https://quarto.org/docs/websites/

Why Quarto for Websites?

• You don’t need to learn anything new for page content
• You get nice website features out of the box: GitHub links, social cards, navigation, etc.
• A lot of customization available via YAML options
• Customize style as much (or as little) as you want

Post Work

I’ll post in Slack

• Share your URL

• Ask questions in Slack

• Get your website off Posit Cloud

• Get set up to work locally

• Explore other publishing methods

Thank you!

Special thanks to Lydia for organizing, coordinating and facilitating