AGENTS.md

Course website and materials for Stat 20 (UC Berkeley), built with Quarto.

Layout

  • _quarto.yml: site-wide config (navbar, announcement banner, theme, includes).
  • 1-questions-and-data/ … 5-prediction/: course units (notes, labs, slides, etc.).
  • _schedule.yml: drives the schedule and what’s published, via the scheduled-docs extension (generates scheduled-docs_files/).
  • assets/: styles (styles.scss), images, and includes/ (shared snippets and HTML injected into pages).
  • docs/: documentation for course staff (shown on the staff site only).

Profiles and outputs

  • Student site (default profile): renders to _site/.
  • Staff site (--profile staff-site, see _quarto-staff-site.yml): renders to _staff-site/ and shows drafts.
  • Solutions (--profile staff-site,solutions).
  • _site/ and _staff-site/ are local previews only (gitignored). The live sites are built and published by GitHub Actions in .github/workflows/ on push to main and on a schedule.

Rendering

  • After every change, rerender whatever it affects so the local previews stay current, for both the student and staff profiles:
    • quarto render path/to/file.qmd
    • quarto render path/to/file.qmd --profile staff-site
  • Site-wide changes (_quarto.yml, assets/styles.scss, assets/includes/) affect every page. At minimum rerender the homepage (index.qmd) under both profiles; ask before doing a full-site render.
  • Invoke quarto render directly. Don’t wrap multiple renders in shell loops or compound commands, and don’t chain a render with &&: run the render first, then run anything else separately.

Gotchas

  • .gitignore ignores *.html (render by-products). Hand-written HTML needs an exception; assets/includes/*.html already has one.
  • Treat generated PDFs as build artifacts: don’t edit them directly. Change the source .qmd and regenerate with Quarto.