From Zero to Website with Quarto

Cascadia R Conf 2026

Charlotte Wickham

From Zero to Website with Quarto

Find the Slack channel #workshop-quarto-2026 in the main conference Slack
Check you’ve completed the steps on the Pre-work page.

Workshop website

Hello, I’m Charlotte Wickham

Developer Advocate
Quarto @ Posit

Based in Corvallis, OR

cvwickham
cwickham
charlotte.wickham@posit.co

Workshop website

Your Turn

Introduce yourself to your neighbors:

Name
Location
What you need a website for

Check you are all set up

Outline

Goal: You create a website with Quarto

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

BREAK: 3:00 – 3:15pm

What to expect

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

Your Turns: You practice what you’ve just seen.

Ask questions:

During Your Turns ( Pink Post-it: Send help!)
After Your Turns
In Slack channel

1. Don’t start from scratch

Demo: Start from a template

From a new empty project:

Terminal

quarto use template cwickham/website-starter

Your Turn: Get the starter template

Start a new project.
RStudio > New Project
Positron > New Folder from Template > Empty Project
Get the template:
```
Terminal
```
```
quarto use template cwickham/website-starter
```
Create a subdirectory for template? No
Open and preview index.qmd. (Put up orange Post-it)
Match the content in index.qmd to the preview.

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. Find other icons at https://icons.getbootstrap.com/
Challenge: Use a different image, and edit image-alt

Spare time? Edit the content of the page

Demo: Use a different `image`

Move new image into project
Replace path
Edit image-alt

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

What is a Quarto website?

A minimal website only needs two files:

_quarto.yml

project: 
  type: website

Tells Quarto this is a website project

index.qmd

---
title: My homepage
---

Becomes index.html the homepage

What else is in this template?

website/
├── _quarto.yml   
├── index.qmd      
├── profile.jpg   # Used in `index.qmd` 
├── _brand.yml    # Theming
├── styles.scss   # Custom styles, none defined`
├── _examples/    # For teaching, not in website
├── README.md     # For GitHub, not in website
└── _site/        # Fully rendered site, .gitignored

Demo: Add a page

New Quarto Document: projects.qmd

projects.qmd

---
title: Projects
---

Some projects I've worked on:

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

Folder structure determines URLs

website/  
├── _quarto.yml      
├── index.qmd         { base url }
├── about.qmd         { base url }/about.html  
├── reports/                   
|    ├── index.qmd    { base url }/reports/   
|    └── feb.qmd      { base url }/reports/feb.html 
└── data/             
    └── sales.csv     { base url }/data/sales.csv

{ base url }: http://localhost:XXXX when previewing locally

Your Turn

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

Spare time: Add content to the page

3. Make the style your own

Use brand.yml: Color

_brand.yml

color:
  foreground: "#333333"  # font color
  background: "#ffffff"  # background color
  primary: "#333333"     # navbar and links

Demo: Change primary

Positron command: Show or Focus Standalone Color Picker

Brand Guide: https://quarto.org/docs/authoring/brand.html

Use brand.yml: Fonts

_brand.yml

typography:
  fonts:
    - family: Open Sans
      source: bunny
    - family: Roboto Slab
      source: bunny
  base:
    family: Open Sans
  headings:
    family: Roboto Slab

Demo: Add these to _brand.yml

bunny: Bunny Fonts, zero-tracking and no-logging policy https://fonts.bunny.net

Demo: Check accessibility with `axe`

Once you start playing with colors it’s easy to create contrast issues.

Check with axe-core by adding:

_quarto.yml

format:
  html:
    axe:
      output: document

Remove before publishing!

Your Turn

Edit _brand.yml to customize colors and fonts
Enable the axe checks to check for contrast issues

Brand Guide: https://quarto.org/docs/authoring/brand.html#brand-elements

Use brand.yml: Code

If your pages have code, you will probably want to tweak monospace options:

_brand.yml

typography:
  monospace-inline:
    color: "#6b21a8"
    background-color: background 
  monospace-block:
    background-color: "#eaf2fb"

Use brand.yml: Dark mode

Add light and dark to colors to add a dark mode toggle to your site:

_brand.yml

color:
  foreground: 
    light: "#333333"
    dark: "#ffffff"
  background: 
    light: "#ffffff"
    dark: "#333333"
  primary: 
    light: "#333333"
    dark: "#ffffff"

Name colors under `color: palette` to more easily refer to them

_brand.yml

color:
  palette:
    white: "#ffffff"
    grey: "#333333"
    pink: "#b70ca6"
  foreground: grey
  background: white
  primary: grey

Sometimes you might need to add SCSS

Apply styles.scss to all pages:

_quarto.yml

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

styles.scss

/*-- scss:defaults --*/
// Set SASS variables: https://quarto.org/docs/output-formats/html-themes.html#sass-variables
$navbar-fg: $brand-white;

/*-- scss:rules --*/
// CSS rules 
.navbar-title {
  color: lighten($brand-pink, 50%);
}

h1 {
  color: $brand-pink;
}

See _examples/brand-scss.

Aside: The three parts of `_quarto.yml`

_quarto.yml

project: # Project options 
  type: website

website: # Website options 
  title: "My Website"
  search: false
  open-graph: true # https://quarto.org/docs/websites/website-tools.html#open-graph
  page-footer: "Made with ❤️ and Quarto"
  navbar:
    right:
      - text: Home
        href: index.qmd
    tools: 
      - icon: github
        text: Github
        href: https://github.com

format: # Page 'html' format options
  html:
    theme: [brand, styles.scss]

Reference: Projects > Websites, and Formats > HTML

4. Publish

Demo: Use `quarto publish`

Terminal

quarto publish posit-connect-cloud

Other venues: gh-pages, netlify, connect

Updates? Re-run quarto publish

Pick one of:

Your Turn: Posit Connect Cloud
Your Turn: GitHub Pages

Your Turn: Posit Connect Cloud

Publish your site to Posit Connect Cloud:

Terminal

quarto publish posit-connect-cloud

Challenge: find the setting to customize the URL.

Your Turn: GitHub Pages

Make your project a Git repo.
Commit, and push to GitHub
Publish to GitHub Pages:
```
Terminal
```
```
quarto publish gh-pages
```

Which venue is right for you?

Provider	Private Source	Private Site	Custom Domain
Posit Connect Cloud	✔️	Paid plans	Paid plans
GitHub	Paid plans	GitHub Enterprise Cloud only	✔️
Netlify	✔️	Paid plans	✔️

Or Posit Connect if your org has it.

Other publishing workflows

Posit Connect Cloud:
- Use Posit Publisher extension in Positron or VS Code
- Connect directly to GitHub repo
Continuous integration: https://quarto-tdg.org/websites.html#sec-ci

Website metadata: search engines

Set title, description and site-url.

E.g. for this workshop’s website:

_quarto.yml

website:
  title: Zero to Website with Quarto
  description: "Zero to website with Quarto Workshop for Cascadia R Conf 2026"
  site-url: https://cwickham.github.io/cascadia2026

Website metadata: social cards

Add a 1200 × 630 px image and image-alt:

_quarto.yml

website:
  image: thumbnail.jpeg
  image-alt: "Zero to Website with Quarto with a screenshot of a website titled 'Alicia, Data Scientist'."
  open-graph: true

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

See more examples at: https://charlotte.quarto.pub/listings/

Listing contents: can be a YAML file

Items link to path.

_examples/listing-talks/talks.yml

- date: 2025-03-12
  title: "From Notebook to Production: Deploying ML Models with Confidence"
  description: "A practical walkthrough of taking a model out of a Jupyter notebook and into a reproducible, monitored production pipeline—covering containers, CI/CD, and drift detection."
  venue: "PyData Seattle"
  path: "https://example.com/talks/notebook-to-production"

- date: 2024-11-08
  title: "The Art of the Reproducible Report"
  description: "Why your analysis should run end-to-end with a single command, and how literate programming tools like Quarto make stakeholder-ready reports painless."
  venue: "posit::conf"
  path: "https://example.com/talks/reproducible-report"

- date: 2024-06-04
  title: "Causal Inference for the Skeptical Analyst"
  description: "Correlation isn't causation, but we can do better than throwing up our hands. An accessible tour of difference-in-differences, propensity scores, and when to trust them."
  venue: "useR! Conference"
  path: "https://example.com/talks/causal-inference-skeptical-analyst"

Listing contents: can other pages

Items link to page.

_examples/listing-projects
└──projects
    ├── coastal-sensors.qmd
    ├── forest-canopy.qmd
    ├── watershed-forecasting.qmd
    └── images

projects/coastal-sensors.qmd

---
title: "Coastal Sensor Network"
description: "Real-time monitoring of water quality along the Oregon coast using a fleet of low-cost IoT sensors."
image: images/photo-1601698832159-665cbefd11da.jpg
categories: [IoT, Time Series, Dashboards]
---

## Overview

Placeholder content. This project deploys a network of sensors that stream
temperature, salinity, and turbidity readings into a central pipeline, surfaced
through a live dashboard for researchers and the public.

Photo by [Karsten Winegeart](https://unsplash.com/@_karsten) on [Unsplash](https://unsplash.com/photos/_m-Xjo9R_y4).

Your turn: Brainstorm a listing

Brainstorm a list of content you might want to include in your website.
What are the key pieces of information for each item? E.g. title, description, … etc.
Does it make sense to give items each their own page, or to use a YAML file?

See more examples at: https://charlotte.quarto.pub/listings/

Adding a listing page

A listing page is a regular page that uses the listing option.

projects.qmd

---
title: Projects
listing:
  contents: projects
  type: grid
  grid-columns: 2
  categories: true
  filter-ui: false
  sort-ui: false
---

talks.qmd

---
title: Talks
listing:
  contents: talks.yml
  type: table
  filter-ui: false
  sort-ui: false
---

Your turn: Add a listing

Drag the content of one of _examples/listing-projects/ or _examples/listing-talks/ into your website.
Edit at least one item to match your listing idea.
Edit the listing page talks.qmd/projects.qmd to reflect your list.
Play with some of the listing options.

Listing documentation: Types and Options

Your turn: Keep building!

Keep tweaking the content of pages
Delete pages you don’t want (and delete any related nav from _quarto.yml)
Double-check _quarto.yml
Publish any updates

Wrap Up

Quarto Websites

A minimal website only needs two files:

_quarto.yml

project: 
  type: website

index.qmd

---
title: My homepage
---

Building a website

Add pages by adding Quarto documents
Control navigation, website settings, etc. in _quarto.yml
Control colors and fonts in _brand.yml
Two special kinds of pages: listings and about pages

Learning more

Quarto websites documentation: https://quarto.org/docs/websites/
Websites chapter in (in-progress) book: https://quarto-tdg.org/websites.html
Websites video series: https://opensource.posit.co/blog/2024-12-04_websites-workshop/
Learn from other people’s website source: https://quarto.org/docs/gallery/#websites

Q&A

Post Work

Share your URL in Slack
Ask questions in Slack

From Zero to Website with Quarto