This week

• We will build static websites using Quarto and GitHub Pages. We will learn how to render text, code, visuals, and interactive visuals on the website.

• To understand how websites are built in Quarto, we first must understand a bit about how Quarto documents are rendered to produce HTML output.

• It is not essential to understand all the inner workings of this process to be able to create a website. However, it is important to understand which component is responsible for what since this will make it easier to target appropriate help files when you need them!

What does Quarto require to render files?

Quarto combines several different processes together to create documents. The basic workflow structure for a Quarto document:

.qmd → (jupyter) → .md → (Pandoc) → HTML / PDF / etc.

YAML metadata

YAML = Yet Another Markup Language YAML Ain’t Markup Language

It is a data-oriented language structure used as the input format for diverse software applications. It is not a markup language but a serialization language — it converts objects into a transmittable/storable format (a series of bits) that can later be reconstructed.

YAML metadata

A typical Quarto YAML header:

---
title: My Quarto Website
author: Meredith Franklin
format: html
---

The YAML metadata affects the code, content, and the output. It is processed by jupyter, Quarto, and Pandoc.

• The title and author fields are processed by Pandoc to set template variables.

• The format field is used by Quarto to determine the output format and apply the appropriate rendering pipeline.

Beyond Pandoc

Note that not all Quarto documents are processed identically. Some output formats use JavaScript rendering in the browser:

• revealjs slides (like these!) pass Markdown content to the Reveal.js JavaScript library, which renders slides in the web browser.
• Observable JS chunks run directly in the browser, enabling reactive data visualizations without a server.
• Hugo is a popular standalone static site generator that builds sites from .md files with no language runtime required.

Summary: Rendering Quarto

In short: quarto render = code execution (jupyter) + Pandoc

Website basics

The most common components of a web page are HTML, CSS, and JavaScript. HTML is relatively simple to learn, but CSS and JavaScript can be much more complicated, depending on how much you want to learn and what you want to do with them.

You don’t need to know much of HTML, CSS, or JavaScript to develop a website using Quarto. If you want to tweak the appearance of your website, you must have some basic knowledge of web development.

HTML basics

HTML = Hyper Text Markup Language. HTML is a standard markup language (not programming language) that provides the primary structure of most websites.

HTML defines the basic structure of a web page. HTML pages are static — the content is not dynamically computed on load.

All elements in HTML are represented by tags. Most HTML tags appear in pairs, e.g., <span style="background-color: #33FF99">highlighted text</span> → highlighted text.

HTML basics

There are a few exceptions, such as the <img> tag, which can be self-closed: <img src="foo.png" />.

An HTML document consists of a head section (metadata, CSS links) and a body section (content).

You can inspect HTML and CSS in your browser: right-click → View Source or Inspect.

Helpful HTML

Font size and color: <font size="3" color="red">Text here!</font>

Columns: <div class="col2"> ... </div>

Centered text: <center>**Here the text is centered.**</center>

Small image right-aligned: <div align="right"><img src="images/fig.png" width="150px"></div>

Large image centered: <center><img src="images/fig.png" width="500px"></center>

CSS basics

CSS = Cascading Stylesheets. It describes the visual style of HTML documents:

• Color palettes
• Images
• Layouts / margins
• Fonts

as well as interactive components like drop-down menus, buttons, and forms.

CSS basics

There are 3 ways to define styles:

• In-line with HTML
• Placing a <style> section in your HTML document
• Define CSS in an external file referenced as a <link> in your HTML (most flexible)

JavaScript

JavaScript is a programming language (unlike HTML and CSS) that makes web pages interactive and dynamic.

As a data scientist building a Quarto website, you rarely write JavaScript directly. Instead, Python libraries generate it for you:

• plotly → outputs a <script> block that renders your chart interactively
• itables → outputs JS that makes your table sortable and searchable
• Dash/Streamlit → JS handles the reactive UI in the browser

JavaScript: what you need to know

You don’t need to write JS, but it helps to know:

• Interactive HTML widgets on your site require JS to be enabled in the browser
• The <script> tags you see in your rendered HTML are JavaScript
• If a plot isn’t rendering, check the browser console for JS errors:
  • Chrome/Edge: Cmd+Option+J (Mac) or F12 → Console tab
  • Firefox: Cmd+Option+K (Mac) or F12 → Console tab

Background: Static vs. dynamic websites

A dynamic site relies on a server-side language (e.g., PHP, Node.js) to compute and send potentially different content depending on conditions — for example, serving a personalized user profile page fetched from a database.

A static site consists of static files (HTML, CSS, JavaScript, images), and the web server sends exactly the same content to every visitor. It is just one folder of static files.

Creating websites with Quarto

Quarto has a built-in static site generator (project: type: website), which we will be using. It supports Bootstrap CSS themes as well as custom CSS.

Creating websites with Quarto

We render Quarto websites using quarto render from the project directory, or the Render button in VS Code.

Overview

There are two main steps for creating a personal website hosted on GitHub:

• Create website through local setup
• Deploy website through GitHub setup

Essential elements

The minimum requirement for any Quarto website is an index.qmd and a _quarto.yml file.

Let’s walk through a very simple example: a website with two pages (Home and About) and a navigation bar.

A simple example

First, the configuration file _quarto.yml:

project:
  type: website

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

A simple example (cont’d)

Then two Quarto files, index.qmd:

---
title: "My Website"
---

Hello, Website!

and about.qmd:

---
title: "About This Website"
---

More about this website.

Common elements

Now let’s discuss the essential _quarto.yml, the index.qmd, and other common elements.

Typically when creating a website, there are various common elements you want to include on all pages (output options, CSS styles, header and footer elements, etc.).

Common elements: _quarto.yml

A more detailed _quarto.yml:

project:
  type: website
  output-dir: "."

website:
  title: "My Website"
  navbar:
    left:
      - icon: fa-home
        href: index.qmd
      - text: "About"
        href: about.qmd
    right:
      - text: "External website"
        href: https://www.google.com
  page-footer:
    center: "Copyright 2026"

format:
  html:
    theme: cosmo
    highlight-style: textmate
    include-after-body: footer.html
    css: styles.css

Common elements: _quarto.yml

• The title field under website: sets the site/navbar title.

self-contained: single doc vs. website

For a single .qmd document (e.g., a homework), self-contained: true bundles all JS/CSS into one portable HTML file — useful for emailing or submitting.

For a website, Quarto automatically sets self-contained: false. This means:

• JS/CSS libraries (e.g., plotly.js) are written once to site_libs/ and shared across all pages
• Each page loads them from that shared folder rather than re-embedding them

_quarto.yml: navbar

The navbar element can be used to define a common navigation bar. You can include internal and external links as well as drop-down menus for sites with many pages.

Some capabilities of navigation bars:

• Choose between dark and light navigation bar colors.

_quarto.yml: navbar

• Use icons on the navigation bar. Quarto supports:
  • Bootstrap Icons (e.g., github, twitter, house)
  • Font Awesome (prefix with fa-)

When referring to an icon, use its name (e.g., icon: github, or icon: fa-github).

Common elements: other

• Include a footer via _quarto.yml:

  website:
    page-footer:
      center: "Copyright © 2026 My Name"

  Or via an HTML file referenced as include-after-body: footer.html.

• Style sheets: styles.css

  blockquote {
    font-style: italic;
  }

Rendering and building the site

As you work on individual pages, you can render them with the Render button (or quarto render index.qmd) just as you would a standalone Quarto document.

Rendering an individual page only renders and previews that page, not the entire site.

To render all pages, use quarto render from the project root, or the Build pane in VS Code.

Rendering and building the site (cont’d)

VS Code with the Quarto extension supports live preview of changes to .qmd files, CSS, and configuration files.

Changes to CSS and YAML config files trigger a refresh of the active page. Changes to .qmd files trigger a rebuild of that page.

Note: After editing shared files or configuration, rebuild the entire site to ensure all pages reflect your changes.

Rendering and building the site: command line

From the terminal, run quarto render to render the entire site, or pass a single file to render just that file:

# render the entire site
quarto render

# render a single file only
quarto render about.qmd

# preview with live reload
quarto preview

Rendering and building the site: command line

If you run quarto render from the project directory:

• All .qmd files in the project root are rendered to HTML.
• Files beginning with _ are not rendered (they are treated as includes/partials).
• The generated HTML files and supporting files (CSS, JS) are copied to the output directory (_site by default).
• The _site directory contains a standalone static website ready to deploy.

Note: The includes and excludes fields of _quarto.yml can override this behavior.