Creating
basic websites

Anatomy of a
Quarto website

Page Structure

index.qmd

---
title: "My Cool Document"
format: html
---

The `gapminder.csv` dataset contains data from the [**Gapminder foundation**](https://www.gapminder.org/).

```{r}
#| label: fig-neat-plot
library(tidyverse)
library(brand.yml)

df <- read_csv("data/gapminder.csv")

brand <- read_brand_yml("_brand.yml")

ggplot(df, aes(x = gdpPercap, y = lifeExp)) +
  geom_point(aes(size = pop, color = continent)) +
  scale_x_log10() +
  theme_brand_ggplot2("_brand.yml")
```

Webpages are like any other Quarto document:

1. Start with a YAML header
2. Can include code cells
3. Everything else is markdown content

Website Structure

A minimal website has two files: index.qmd and _quarto.yml

• index.qmd: Renders to index.html, your home page.

• _quarto.yml: Controls project and website properties.

When rendered you will get a _site/ folder. This contains everything needed to serve the site.

_quarto.yml

_quarto.yml

project:
  type: website

website:
  title: "My site"
  navbar:
    left:
      - href: index.qmd
        text: Home

format:
  html:
    toc: true

Quarto projects

Websites are Quarto projects.

All Quarto projects include a _quarto.yml file.

This is a Quarto Project.

my-folder/
├── _quarto.yml
└── my-document.qmd

This is not.

my-folder/
└── my-document.qmd

Quarto projects

A Quarto project is a directory that provides:

• A way to render all or some of the files in a directory with a single command (e.g. quarto render myproject).
• A way to share YAML configuration across multiple documents.

Quarto projects

Not all Quarto projects are websites (though they’re typically website-like).

Terminal

❯ quarto create project
# ? Type
#   default
# ❯ website
#   blog
#   manuscript
#   book
#   confluence

Creating a project skeleton

• RStudio
• Positron / VS Code
• Terminal

File > New Project > New Directory > Quarto Website

Open the Command Palette ( ⌘⇧P |  Ctrl + Shift + P)
and start typing “create project”

Terminal

❯ quarto create project website my-site
# ? Title (my-site) › My site
# Creating project at /Users/andrew/Desktop/my-site:
#   - Created _quarto.yml
#   - Created index.qmd
#   - Created about.qmd
#   - Created styles.css
# ? Open With › (don't open)

Creating a project skeleton

my-site/
├── _quarto.yml
├── about.qmd
├── index.qmd
├── styles.css
└── testing.Rproj  ← if made with RStudio

Your turn

1. Create a new website project somewhere on your computer.

   We’ll use this as a playground throughout the course.

2. Open the project in RStudio and explore what the different files look like.

03:00

Workflow

Preview

• RStudio
• Positron / VS Code
• Terminal

Current page

  ⌘⇧K

 Ctrl + Shift + K

Whole site

Build > Render Website

Current page

  ⌘⇧K

 Ctrl + Shift + K

Whole site

Use Terminal:

Terminal

quarto preview 

Requires Quarto Extension for VS Code

Current page

Terminal

quarto preview index.qmd

Whole site

Terminal

quarto preview 

Your turn

1. Open your playground website.

2. Open index.qmd and click Render/Preview.

3. Edit the title entry in index.qmd’s YAML metadata to something different and add a subtitle entry. Preview.

4. Add some text to index.qmd. Preview.

5. Add an R code chunk to about.qmd. Preview.

05:00

_quarto.yml

_quarto.yml

Configure all site-level settings with _quarto.yml:

_quarto.yml

project:
  type: website

website:
  title: "My site"
  navbar:
    left:
      - href: index.qmd
        text: Home

format:
  html:
    toc: true

Project settings

_quarto.yml

project:
  type: website
  output-dir: _output
  preview:
    port: 5555

Project settings

_quarto.yml

project:
  type: website
  output-dir: _output
  preview:
    port: 5555

Site settings

_quarto.yml

project:
  type: website

website:
  title: "My site"
  description: "Some neat stuff"
  cookie-consent: true
  search: false
  navbar:
    left:
      - href: index.qmd
        text: Home

format:
  html:
    toc: true

Navigation settings

More on this in a bit!

_quarto.yml

project:
  type: website

website:
  title: "My site"
  navbar:
    left:
      - href: index.qmd
        text: Home
  sidebar: 
    style: "docked"
    contents: 
      - about.qmd

format:
  html:
    toc: true

Format settings

_quarto.yml

project:
  type: website

website:
  title: "My site"
  navbar:
    left:
      - href: index.qmd
        text: Home

format:
  html:
    toc: true
    number-sections: true
    cap-location: margin

Don’t memorize this stuff!

Quarto.org > Reference > Websites

Your turn

1. Edit your _quarto.yml to make the following changes:

   • Change the preview port to 5555
   • Enable a cookie consent dialog
   • Add a site description

2. Bonus tasks!

   • Add a footer that says “© 2025, Myself”
   • Add an announcement bar that says something

Advice:

• Don’t try to make all these changes at once! Remember the workflow: edit, save, preview, repeat.
• Use the documentation at Quarto.org > Reference > Websites

07:00

Answer

_quarto.yml

project:
  type: website
  preview:
    port: 5555

website:
  title: "My site"
  description: "Something"
  cookie-consent: true
  page-footer: "© 2025, Myself"
  announcement:
    content: "**Fun!** This is my playground site."
  navbar:
    left:
      - href: index.qmd
        text: Home

Answer

Navigation

Top navigation

_quarto.yml

project:
  type: website

website:
  title: "My site"
  navbar:
    left:
      - href: index.qmd
        text: Home

format:
  html:
    toc: true

Add new page

_quarto.yml

project:
  type: website

website:
  title: "My site"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    toc: true

Entry titles

_quarto.yml

website:
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

• Use href + text to control the link title
• Use the .qmd filename to use that page’s title as the link title

Icons

_quarto.yml

website:
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd
      - href: https://www.github.com
        icon: github

icons.getbootstrap.com

Dropdowns

_quarto.yml

website:
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd
      - href: https://www.github.com
        icon: github
      - icon: share
        menu: 
          - href: https://bsky.app/
            icon: bluesky
            text: Bluesky
          - href: https://www.linkedin.com/
            icon: linkedin
            text: LinkedIn

Don’t memorize this stuff!

Quarto.org > Guide > Websites > Website Navigation

Your turn

1. Create a new file named contact.qmd and paste the content from about.qmd into it. Then change it to something else.

2. Add contact.qmd to the left section of your top navigation bar.

3. Add a right section to the navigation bar with icon-based links to a few other websites.

4. Bonus task! Create a dropdown menu in the top navigation bar, either with links to other websites or links to some new .qmd pages that you create.

Advice:

• Don’t try to make all these changes at once! Remember the workflow: edit, save, preview, repeat.
• Use the documentation at Quarto.org > Guide > Websites > Website Navigation

07:00

Answer

_quarto.yml

website:
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd
      - contact.qmd
    right:
      - href: https://www.github.com
        icon: github
      - icon: share
        text: Share!
        menu: 
          - href: https://bsky.app/
            icon: bluesky
            text: Bluesky
          - href: https://www.linkedin.com/
            icon: linkedin
            text: LinkedIn

Answer

Side navigation

_quarto.yml

website:
  sidebar:
    contents:
      - href: index.qmd
        text: Home
      - about.qmd
      - contact.qmd

Side navigation and sections

_quarto.yml

website:
  sidebar:
    contents:
      - href: index.qmd
        text: Home
      - section: About me
        contents:
          - about.qmd
          - contact.qmd

Side navigation and other settings

_quarto.yml

website:
  sidebar:
    style: "docked"  # Default is "floating"
    background: "#dddddd"
    logo: img/logo.png
    contents:
      - href: index.qmd
        text: Home
      - section: About me
        contents:
          - about.qmd
          - contact.qmd

Automatic sidebar

_quarto.yml

website:
  sidebar:
    contents:
      - href: index.qmd
        text: Home
      - section: Research
        contents:
          - research/project1.qmd
          - research/project2.qmd
          - research/project3.qmd

_quarto.yml

website:
  sidebar:
    contents:
      - href: index.qmd
        text: Home
      - section: Research
        contents: research/*

Hybrid navigation

Have a different sidebar for different sections!

_quarto.yml

website:
  navbar: 
    left: 
      - href: index.qmd
        text: Home
      - about.qmd
      - text: "Research"
        href: research/index.qmd
  sidebar:
    - title: "Research"
      contents:
        - research/index.qmd
        - research/project1.qmd
        - research/project2.qmd
        - research/project3.qmd

Don’t memorize this stuff!

Quarto.org > Guide > Websites > Website Navigation

Your turn

1. Create a folder named research and create these files in there: index.qmd, project1.qmd, project2.qmd, and project3.qmd

2. Add an entry for research.qmd in your top navigation bar

3. Make a sidebar that only appears on the research page that contains links to index.qmd, project1.qmd, project2.qmd, and project3.qmd

Advice:

• Don’t try to make all these changes at once! Remember the workflow: edit, save, preview, repeat.
• Use the documentation at Quarto.org > Guide > Websites > Website Navigation

07:00

Answer

_quarto.yml

# Excerpt!
website:
  navbar:
    left:
      - href: index.qmd
        text: Home
      - text: "Research"
        href: research/index.qmd

  sidebar:
    - title: "Research"
      contents:
        - research/index.qmd
        - research/project1.qmd
        - research/project2.qmd
        - research/project3.qmd

Answer

Special pages

YAML-based page settings

Some page types are based on special templates that use information from the YAML metadata.

Two main built-in special page types:

• Listing pages
• About pages

(you can make your own special templates too!)

Listing pages

More about these in the advanced section!

research.qmd

---
title: "Research"
listing:
  contents: "*.qmd"
  type: table
---

About pages

about.qmd

---
title: "Ada Lovelace"
about:
  template: solana
  image: img/ada-lovelace.jpg
  links: 
    - icon: wikipedia
      text: Wikipedia
      href: https://en.wikipedia.org/wiki/Ada_Lovelace
toc: false
---

## Background

Augusta Ada King, Countess of Lovelace (née Byron; 10 December 1815 – 27 November 1852), also known as Ada Lovelace, was an English mathematician and writer chiefly known for her work on Charles Babbage's proposed mechanical general-purpose computer, the Analytical Engine. She was the first to recognise that the machine had applications beyond pure calculation. Ada Lovelace is sometimes considered to be the first computer programmer.

Don’t memorize this stuff!

Quarto.org > Guide > Websites > About Pages

Your turn

1. Create a basic About page for either yourself or some fictional person.

   • Find an image on your computer or from the internet and add it to your project, either in the root of project, or (better!) in a folder just for images, like img/
   • Add links to different websites (with icons!)
   • Try different template options
   • Try different image-shape options

Advice:

• Don’t try to make all these changes at once! Remember the workflow: edit, save, preview, repeat.
• Use the documentation at Quarto.org > Guide > Websites > About Pages

07:00

What’s next?

Course outline

• ✅ Intro to Quarto
• ✅ Creating basic websites
• Advanced website features
• Publishing
• Customization and branding
• Interactivity

Break!