Exercise: Build and Publish a Quarto Website

Learning Goal

By the end of this exercise you will have built a small Quarto website on your own computer and published it live on the internet — with a web address you can share. It is written for people who are completely new to Quarto, so each step explains what you are doing and why.

No coding required

A Quarto website is just a folder of plain-text pages. You can build and publish the whole thing without writing a single line of R or Python. If you later want to embed analysis, you can — but that is not needed here.

Before You Start

You will need three things:

Quarto installed, and an editor you are comfortable with. If you have not done this yet, follow Installing Quarto first. You can check your install by running quarto check in a terminal.
A terminal (the Terminal app, PowerShell, or the terminal panel inside your editor). Every command below is typed there.
A free GitHub account, which you will only need for the publishing step near the end. If you do not have one, you can sign up at github.com — or skip Step 6 and still complete everything else locally.

What You Will Build

A small site with two pages — a home page and an about page — connected by a navigation bar at the top, given a colour theme, and finally published to the web. It is intentionally tiny: the point is to see the full path from empty folder to live website.

Step 1 — Create the Website Project

Quarto can generate a ready-to-use website folder for you. In your terminal, move to wherever you keep projects and run:

quarto create project website my-site

You will be asked to provide a title for your website in the terminal, enter what you want or just ‘my-site’.

This makes a new folder called my-site, in the directory that your terminal was set to, navigate into this folder in the file explorer of your editor. It contains a few starter files:

_quarto.yml — the project’s settings file. It controls things that apply to the whole site, like its title, the navigation bar, and the colour theme.
index.qmd — your home page. (index is the special name web servers look for first.)
about.qmd — a second example page.
styles.css — a place for custom styling (you will swap this for a nicer option in Step 5).

Prefer buttons to typing?

You do not have to use the terminal to create the project. The same wizard is available through your editor: in Positron or VS Code open the command palette and choose Quarto: Create Project → Website Project; in RStudio use New Project → Quarto Website. The result is the same starter folder.

Step 2 — Preview Your Site

Option 1: Open one of your pages such as index.qmd in your editor and click the Preview button at the top of the file editor window. This opens a live preview of the page in your browser.

Option 2: In your terminal, make sure you are in the my-site folder and start a live preview:

quarto preview

The page will be opened in the viewer window on the right side of your editor. You can also open it in your default browser by clicking the link in the terminal. Leave this command going while you work — every time you save a file, the preview refreshes automatically so you can see changes instantly. Press Ctrl + C in the terminal to stop it later.

Step 3 — Understand `_quarto.yml`

Open _quarto.yml. This is the one file that ties the site together. A minimal version looks like this:

project:
  type: website

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

format:
  html:
    theme: cosmo
    toc: true

Reading it from top to bottom:

project: type: website tells Quarto to treat the whole folder as one website rather than a single document.
website: title: is the name shown in the browser tab and in the top-left of the navigation bar. Change it to something of your own.
navbar: is the menu across the top. Each entry has an href (the page it links to) and the text shown for it. Adding a page to your site is mostly a matter of adding a line here.
format: html: sets options for every page at once — here, the cosmo theme and a table of contents (toc).

Change the title to your own and save. Watch the preview update.

Step 4 — Edit the Home Page

Open index.qmd. Below the --- header, the content is just Markdown — the same headings, lists, links, and callouts you have already met in this workshop. Replace the starter text with a short welcome:

---
title: "Welcome"
---

A small site I built while learning Quarto. Use the menu above to look around.

Step 5 — Adding an About Page

Your starter project already includes a second page, about.qmd. Quarto has a dedicated About layout that turns an ordinary page into a tidy profile — a photo, a short bio, and a row of links to your professional profiles. You switch it on by adding an about: block to the page’s front matter. The full reference is in the Quarto About Pages guide.

Open about.qmd and replace its contents with:

---
title: "About Me"
image: profile.jpg
about:
  template: jolla
  image-shape: round
  image-width: 12em
  links:
    - icon: github
      text: GitHub
      href: https://github.com/your-username
    - icon: envelope
      text: Email
      href: mailto:you@example.com
    - icon: mortarboard
      text: Google Scholar
      href: https://scholar.google.com
---

I am a researcher working on something interesting. I built this site while learning Quarto.

Drop a photo of yourself named profile.jpg next to the page — or point image: at any image you have, or remove that line to skip the photo entirely.

Reading the about: block:

template: chooses the overall layout. Quarto ships five, each arranging the photo, bio, and links differently: jolla (centred photo with links below — a clean personal profile), trestles, solana, marquee, and broadside. Swap the name and watch the preview rearrange until one fits.
image:, image-shape: (round, rounded, or rectangle), and image-width: control how the photo appears.
links: is the row of profile links. Each entry has an href, the text shown, and an icon. Everything below the front matter becomes your bio.

The icon: names come from the built-in Bootstrap icon set, which covers the common ones (github, twitter, linkedin, envelope, and so on).

Icons for academic services

The built-in Bootstrap icons don’t include some services researchers rely on, such as ORCID and ResearchGate. For those, add the Font Awesome extension, which brings roughly 2,000 more icons (including academic brands). Install it from inside your project folder:

quarto add quarto-ext/fontawesome

Then drop its shortcode wherever you want an icon — for example, a small link row in your bio:

[ ORCID](https://orcid.org/0000-0000-0000-0000)
[ ResearchGate](https://www.researchgate.net/profile/your-name)

Brand icons need the brands keyword. Browse the full set at fontawesome.com.

Step 6 — Add a Publications Page (a Listing)

So far you have written every page by hand. Quarto can also build a page for you from a data file — this is called a listing. Listings can be used for blogs, presentations or even staff pages and as usual the Quarto guide provides a lot of detail on how to do this here. In this exercise however we will use it to make a page listing your scientific publications. This is actually a more advanced use-case and uses a custom listing template that the authors developed for their own sites.

The approach has three ingredients:

A data file (.yaml) holding the details of each publication — title, authors, year, DOI, links, and so on.
A template (.ejs) that controls how each entry is laid out.
A page (.qmd) with a listing block that points at the data and the template.

You don’t have to write the data file or the template from scratch — download the two starter files below and save them into your project:

Download publications.yaml

Download publication_yearly.ejs

Keep things tidy by giving each file its own folder inside your project:

put publication_yearly.ejs in a new folder called ejs/, so it lives at ejs/publication_yearly.ejs
put publications.yaml in a new folder called publications/, so it lives at publications/publications.yaml

Open publications.yaml to see how it is built. It contains a single complete example entry. Each publication is a list item (it begins with a -) carrying fields such as title, authors, year, doi, and an optional summary. To add your own work, copy the whole block and fill in your details; empty fields like code_url: '' simply don’t appear.

Let your reference manager do the typing

You don’t have to fill in publications.yaml entirely by hand. Most of these fields already live in your reference manager. Export your publications as a BibTeX (.bib) file from whichever tool you use — Zotero, Mendeley, EndNote, and others all support this — and use it to populate the YAML. That keeps your publications page in step with the library you already maintain.

With the data and template in place, create the page that ties them together. Make a new file called publications.qmd next to your other pages and paste in:

---
format:
  html:
    anchor-sections: true
listing:
  - id: Journal-articles
    template: ejs/publication_yearly.ejs
    contents:
    - publications/publications.yaml
    field-display-names:
      summary: "Summary"
    field-types:
      summary: raw
---

## Journal Articles
::: {#Journal-articles}
:::

Reading the front matter:

listing: tells Quarto to build a listing, here given the id Journal-articles.
template: points at the .ejs file in your ejs/ folder, which decides how each entry looks.
contents: points at the data file in your publications/ folder.
field-types: summary: raw lets the rich HTML summaries in the data file render as formatted text instead of as plain characters.
The empty ::: {#Journal-articles} block in the body is the placeholder where Quarto drops the finished listing.

Finally, a new page is invisible until you link it. Add it to the navbar in _quarto.yml:

    left:
      - href: index.qmd
        text: Home
      - href: about.qmd
        text: About
      - href: publications.qmd
        text: Publications

Save and check the preview — your publications should appear as a clean, consistent list, each entry formatted by the template rather than by hand.

Note

A publications page needn’t stop at journal articles. Because each listing is simply a data file plus a template, you can stack several on a single page — one for journal articles, another for theses, talks, datasets, or software. For an example built this way, see Ben’s publications page, which combines multiple listings for different kinds of research output.

Step 7 — Change How It Looks

The quickest way to restyle a site is to pick a different built-in theme. Quarto ships with many; try swapping cosmo for another such as flatly, litera, or sandstone in _quarto.yml and watch the preview change.

To go a little further, you can override individual colours with a small style file. Create a file named styles.scss containing:

/*-- scss:defaults --*/

// a couple of colour tweaks
$navbar-bg: #2c3e50;
$link-color: #18bc9c;

The /*-- scss:defaults --*/ line at the top is required — it tells Quarto these are style variables. Then layer it on top of your theme in _quarto.yml:

format:
  html:
    theme: [cosmo, styles.scss]
    toc: true

(You can now remove the original styles.css line if your config still references it.)

Going further with branding

Picking colours by hand is fine for one site. When a whole research group or project wants a shared, consistent look across its website, slides, and documents, Quarto offers a dedicated branding file — see Using brand.yml in the advanced topics. Treat that as a later step; clear structure matters more than polish when you are starting out.

Step 8 — Publish to GitHub Pages

Your site only exists on your laptop so far. GitHub Pages is a free service that turns a GitHub repository into a live website, and Quarto can publish to it with a single command.

First, put your project on GitHub:

On github.com, create a new, empty repository (no README) named, for example, my-site.
Back in your terminal, inside the project folder, connect your files to it:

git init
git add .
git commit -m "First version of my site"
git branch -M main
git remote add origin https://github.com/YOUR-USERNAME/my-site.git
git push -u origin main

Now publish:

quarto publish gh-pages

Quarto renders your site, copies the finished pages onto a special branch called gh-pages, and switches on GitHub Pages for you. After a minute or so it prints your live address, which will look like https://YOUR-USERNAME.github.io/my-site/. Open it — your site is on the internet.

What is the gh-pages branch?

It is a separate branch that holds only the built website (the HTML), kept apart from your editable source files on main. You normally never touch it by hand — quarto publish manages it for you.

Publishing automatically

Running a command each time works well, but you can also have the site rebuild itself every time you push a change. This very workshop site does that with a small GitHub Actions workflow file, so no one has to remember to publish. Once you are comfortable with the manual command, the Quarto publishing docs show how to set the automatic version up.

Step 9 — Make a Change and Republish

Edit one of your pages — add a sentence to the home page, for instance — and save. Then run:

quarto publish gh-pages

again. Refresh your live URL after a moment and your update is there. This edit-and-republish loop is the whole rhythm of maintaining a Quarto website.

Stretch Tasks

If you finish early, try one of these:

Add a footer to the bottom of every page using a page-footer: entry under website:.
Move your navigation into a sidebar instead of (or as well as) the top navbar.
Add a fourth page and link it.
Try a custom Google Font by importing it in styles.scss and setting mainfont: in the HTML format options.

Expected Outcome

You should now have:

a small Quarto website project with at least two linked pages,
a colour theme of your choosing,
and a live URL you can share with anyone.

Self-Check

Ask yourself:

Does the site open and refresh when I run quarto preview?
Does every item in the navigation bar go to the right page?
Can I visit my site at its github.io address from a different browser or device?
Could I add another page and republish without looking up the steps?

Learning Goal

Before You Start

What You Will Build

Step 1 — Create the Website Project

Step 2 — Preview Your Site

Step 3 — Understand _quarto.yml

Step 4 — Edit the Home Page

Step 5 — Adding an About Page

Step 6 — Add a Publications Page (a Listing)

Step 7 — Change How It Looks

Step 8 — Publish to GitHub Pages

Step 9 — Make a Change and Republish

Stretch Tasks

Expected Outcome

Self-Check

Step 3 — Understand `_quarto.yml`