Building a Quarto Website and Using GitHub

Eleana Cabello

2025-07-18

Class Reminders

  • Final Project Proposal
    • Submit to Canvas by July 22nd
    • ~5 min presentation on July 22nd
  • Final Project Presentations
    • Dates - July 24th and 28th
    • 5-10 min walkthrough of your .qmd file from your website
  • Assignment 1-3 due July 25th!

Github

  • Online based platform that is used, along with git, for version control of software projects and makes collaboration easier between developers

  • Version control means tracking modifications, creations, and deletions of project files

  • Connects your local development enviroment, or local repository, to online/cloud based storage, remote repository, to keep track of modifications and make it easier to share with others

Quarto

  • Open-source scientific and technical publishing system that allows for the use of narrative text with code

  • However not just limited to a singular file, allows for easy setup of other types of project like websites, presentations, dashboards, books, etc.

  • The ability to change formats easily and incoporate other languages than only R removes previous limitations and allows for better communication of projects and workflows

Project Benefits of using Github and Quarto

  • Easier Publication Submission - Everything is together and well documented (hopefully🤞) to be submitted for publication

  • Reproducibility - allows others to easily have access to how an analysis was done and be able to replicate it

  • Branding - Having an online resume/cv of all your projects and those you have collaborated on with others

Example Websites

Setting Up Your First Quarto Website on GitHub

0 - Create a GitHub Folder for all your future projects

1 - Setup Repository Online

Log in to your GitHub account.

Click on the New Repo button.

Name your repo with purpose (your name for a personal website, a project name, a course name, etc.)

Click the Create Repository button.

Once on the page below, click Set up in Desktop.

2 - Set Up Remote Repository Locally through Github Desktop

Once in Github Desktop, pick what directory you would like to store the repository locally. This action will create a remote repository connecting it to the one you have online.

Try to keep organized and do this in a directory dedicated to your GitHub projects.

3 - Open RStudio and Set Repository as Working Directory

Navigate to your remote repository through the files window.

Once in the remote repository, click the gears icon and Set As Working Directory.

4 - Setting Up Quarto Website Project in Repository

Make sure your working directory is in your local repository

Find the terminal tab in your RStudio window:

4 - Setting Up Quarto Website Project in Repository

Type the following command in the terminal to create an RProject and setup a quarto website, a new window of RStudio will appear:

quarto create project website

When asked for Directory put . for the current directory and when asked for a Title give it the title of your project with no spaces (use _ instead):

On the new Rstudio window refresh and check out the new files by refreshing the files window:

  • _quarto.yml
  • index.qmd
  • about.qmd
  • styles.css

5 - Commiting and Pushing to Github Repository

In Github desktop type a commit message and commit to main.

After commiting your changes and message, hit publish to origin.

Back in your GitHub account, you should see the brown circle indicating GitHub is going through your workflow file and setting up your website:

After it has completed successfully the brown circle should turn to a green check mark, if it is not successful it will turn into a red x:

6 - Setting Up to Publish to Github Pages using a gh-pages branch

In Github website refresh and view all branches in the repository by following the steps below:

Make sure to name it gh-pages, it has to be named this in order for your website to work.

7 - Setting Up Github Pages and Workflows Locally

Back in R studio do the following:

  • Create text file named .nojekyll, it does not need to contain anything

  • Create .github folder in your working directory

  • Create a folder named workflows inside the .github folder

  • Create a text file named publish.yml inside the folder .github/workflows

  • Copy and paste below into the publish.yml:

publish.yml
on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

8 - Commit and Push Changes to Host Website on Github Pages

9 - Check Settings and Website

Navigate to settings of your repository.

Then navigate to pages.

In pages make sure that under Build and Deployment Source is Deploy from Branch. Also make sure that under Branch that gh-pages is selected from /(root) like below:

10 - Visit Your Website!

Customizing Your Website

Lets edit your Home Page: index.qmd

index.qmd
---
title: "NAME"
toc: false
about:
  template: trestles
  links:
    - text: GitHub
      href: link
    - text: Email
      href: link
---

::: {.column-page}

## Bio

## Research Goals

## Experience

:::

Setting up your project

  • Create a new Quarto document named projects - projects.qmd - with the following content:
projects.qmd
---
title: "Projects"
listing:
  id: projects-listings
  contents: projects
  sort: "date asc"
  type: table
  categories: false
  sort-ui: false
  filter-ui: false
page-layout: full
title-block-banner: false
date-format: "MM-DD-YYYY"
---

::: {#Projects-listings}
:::

  • Create a projects folder

  • Move about.qmd to the projects folder and rename it to your project_title.qmd (Change to your project title or something descriptive!)

  • Now change the listing in the _quarto.yml:

_quarto.yml
website:
  title: "Test_website"
  navbar:
    right:
      - href: index.qmd
        text: Home
      - href: projects.qmd
        text: Projects
  • Change the title of your website here as well!

Changing your publish.yml to run R code

To run your Quarto R code cells/blocks and have their output displayed on your website (without errors) you must add R enviroment development step to your workflow file:

publish.yml
name: Quarto Publish

on:
  workflow_dispatch:
  push:
    branches: main
    
jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: '4.2'
      
      - name: Set up R Dependencies 
        uses: r-lib/actions/setup-r-dependencies@v2
        with:
          packages:
            any::knitr
            any::rmarkdown
            any::tidyverse
            any::tidymodels
            any::GGally
            any::ggstats
            any::cowplot
            any::lme4
            any::lmerTest
            any::psycModel 
            
      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Add your dataset to your working directory

Since we have time - Make it more personal

  • Change .css to .scss and change the file to the following:
styles.scss
/*-- scss:defaults --*/

// Colors
$dark-green: #596b57;
$light-green: #D1D9CE;
$cream: #FDFBF7;
$gray: #64605f;
$orange: #ad7237;
$black: #151617;

// Base document colors
$navbar-bg: $dark-green; // navbar
$navbar-fg: $cream; // navbar foreground elements
$navbar-hl: $light-green; // highlight color when hovering over navbar links
$body-bg: $cream; // page background 
$body-color: $black; // page text 
$footer-bg: $cream; // footer 

// Inline code
$code-bg: $cream; // inline code background color
$code-color: $orange; // inline code text color
  • In _quarto.yml change the following:
_quarto.yml
format:
  html:
    theme: styles.scss
    toc: true

Other Resources