Appendix B — Quarto Websites

B.1 Where this appendix fits

The main pathway begins with R Markdown so students can see code and output one step at a time. Use this optional appendix after students can knit a complete analysis and are ready to organize several pages as a website.

B.2 What Quarto does

Quarto combines Markdown, executable code, citations, and outputs into a website or report. A publishable data project should render from a fresh R session without relying on objects left in the Console.

B.3 From R Markdown to Quarto

R Markdown and Quarto both combine prose, code, and output. The R Markdown chapters have already introduced the essential ideas: a short header, Markdown text, R code chunks, and a complete render. Quarto applies the same model to a more flexible website and book system.

Quarto is used here because this textbook is a Quarto book and because Quarto is Posit’s next-generation system for this kind of document. Students do not need Quarto for the early analysis exercises; they can move from .Rmd to .qmd when a multi-page publication is useful. See the official Quarto introduction and R Markdown user FAQ for the relationship between the two systems.

Current RStudio releases include Quarto. To verify the command-line tool, run this in the Terminal, not the R Console:

quarto check

The R package named quarto is optional; it is not required to render a Quarto project from RStudio or the Terminal.

B.4 Create a website project

In RStudio, choose File → New Project → New Directory → Quarto Website. A basic project contains:

  • _quarto.yml — site-wide configuration;
  • index.qmd — the home page;
  • other .qmd pages;
  • optional styles.css; and
  • an .Rproj file.

Use folders such as:

project/
├── _quarto.yml
├── index.qmd
├── methods.qmd
├── analysis.qmd
├── data/
├── images/
└── outputs/

B.5 Configure navigation correctly

For a Quarto website, navigation belongs under website: navbar::

project:
  type: website

website:
  title: "My Data Story"
  navbar:
    left:
      - text: Home
        href: index.qmd
      - text: Methods
        href: methods.qmd
      - text: Analysis
        href: analysis.qmd

format:
  html:
    theme: cosmo
    toc: true

Use .qmd targets in the configuration. Quarto creates the corresponding HTML files during rendering.

B.6 Make every page reproducible

Each page should load the packages and data it needs. Do not assume another page runs first.

library(tidyverse)

analysis_data <- read_csv("data/analysis_data.csv")

Test with:

  1. Session → Restart R;
  2. delete any temporary objects from the Environment;
  3. run quarto render from the project root; and
  4. inspect the rendered site and Terminal output.

B.7 Preview locally

Preview locally with the RStudio Render button or:

quarto preview

B.8 Publish with GitHub Pages

This textbook uses GitHub Pages. Quarto renders the finished website into the docs/ folder. Commit both the revised .qmd sources and the regenerated docs/ files, push them to GitHub, and configure GitHub Pages to publish from the docs/ folder on the main branch.

This approach keeps the source, revision history, and website in one repository. It also means the textbook is not affected by the closure of a separate publishing service.

B.9 Other publishing services

Posit now recommends Posit Connect Cloud for new Quarto publishing. Quarto 1.9 and current RStudio releases can publish Quarto documents and websites to Connect Cloud, including through its free tier for static content.

Quarto Pub is being retired

Posit has stopped new Quarto Pub account creation. Publishing new material or revisions to Quarto Pub will end on December 31, 2026. Existing content is expected to remain available during the announced migration period. Do not build a new course workflow around Quarto Pub. See Posit’s migration announcement.

Publishing is not a substitute for archiving. Preserve the source data, code, and a dated methods note in a repository or institutional storage location.

B.10 Include files readers need

Quarto automatically includes figures generated by a page, but downloadable data or standalone assets may need to be declared:

project:
  type: website
  resources:
    - data/*.csv
    - downloads/*

Do not publish sensitive data, credentials, embargoed material, or files you do not have permission to redistribute.

B.11 Accessibility and verification

Before publishing:

  • add informative alt text to images;
  • use descriptive link text instead of “click here”;
  • ensure color is not the only way a chart communicates meaning;
  • test the site on a phone-sized window;
  • check that navigation and download links work;
  • verify titles, captions, sources, units, and dates; and
  • render once from a clean session.

B.12 Removing a published site

Deleting the local folder does not remove a published copy. Use the provider’s site dashboard to delete it. Confirm the exact target before deletion; a published URL may already be cited or shared.

B.13 Takeaways

Command or file How it is used Why it is useful
.qmd Combines explanation, R code, and output Produces a reproducible document after the analysis skills are established
_quarto.yml Defines site structure, navigation, and format Keeps settings consistent across pages
quarto preview Builds and opens a temporary local preview Supports checking changes before publication
quarto render Rebuilds the complete output site Confirms that every page works from the project files
docs/ Stores the rendered GitHub Pages website Separates publishable output from chapter source files