Build Your Academic Website with Quarto and GitHub

A guided lab for PhD economics students

A beginner-friendly walkthrough for creating a personal academic website using Quarto, RStudio, Git, and GitHub Pages.

Goal for today

By the end of this lab, you will have a starter academic website that lives in your own GitHub repository and can be published online with GitHub Pages.

We will use my personal website repository as the starting point:

https://github.com/laurenchenarides/website

You will make your own copy, edit the pages in RStudio, render the website with Quarto, and push your changes to GitHub.

This lab follows a basic GitHub workflow process:

  1. Keep project files organized in a folder.
  2. Track changes with Git.
  3. Store and share your project on GitHub.
  4. Use Quarto to turn plain text files into a polished website.
  5. Publish the site using GitHub Pages.

Before you build a website

Before spending time designing a website, make sure the basic pieces of your professional presence are in good shape.

For most PhD students, these include:

  • your CV
  • your department or school profile page
  • your Google Scholar page
  • your LinkedIn page
NoteTime is a resource

A personal website can be useful, but it should not come at the expense of the basics.

Before you spend time customizing colors, layouts, fonts, or extra pages, make sure your CV is current and easy to read. Also make sure your school profile, Google Scholar page, and LinkedIn page are accurate.

These are often the first places people look for information about you.

For PhD students, these basic materials create a minimum professional presence. Most students on the job market will have a CV, a department profile, a Google Scholar page, and a LinkedIn profile. The question is: how do you differentiate yourself once those basics are in place?

A personal website can help.

Your website gives you a place to organize the information you most want others to see. It can include your research interests, working papers, teaching materials, data projects, media appearances, or other examples of your professional work.

TipWhy build a website?

Your website may not be reviewed carefully at the first stage of the job market.

But it can matter later.

At the flyout stage, departments may want to learn more about you beyond your CV and job market paper. In many cases, those two documents, along with your personal website, are the main materials faculty see before meeting you.

A website gives you a place to add context. It lets you show the work, materials, and professional identity you want people to notice.

Examples: How websites can help you differentiate

Before we start editing files, let’s look at a few examples of academic websites.

Notice how different people use a website to communicate who they are, what they study, and what they want others to remember.

TipWhat to look for

As you look at each example, ask:

  • What is the first thing I learn about this person?
  • What kind of work do they want me to associate with them?
  • What evidence do they provide beyond the CV?
  • Is the website mostly a professional landing page, a research portfolio, or an impact narrative?
  • What would I remember about this person after two minutes?

Example 1: Ujjwol Paudel

Ujjwol Paudel’s website

This is a strong example of a clean academic job-market-style website. The homepage quickly communicates current position, PhD completion, research areas, methods, job market status, CV, upcoming talks, education, and professional links. It is easy to find the basic information someone would want when learning about a PhD student or early-career researcher. :contentReferenceoaicite:0

What this website does well:

  • makes the researcher’s field and methods clear quickly
  • links to the CV, Google Scholar, LinkedIn, and other professional profiles
  • includes a simple navigation structure: About, Research, CV, Teaching, and Miscellaneous
  • foregrounds job market status and recent talks

Differentiation lesson:
This type of website helps visitors quickly understand your research identity and professional status. It is especially useful when you want a clean, low-friction academic presence.

Example 2: Matthew Patrick Rabbitt

Matthew Patrick Rabbitt’s website

This website presents a broader professional narrative around food security research, measurement, policy impact, media, programs, teaching, talks, and awards. The homepage highlights expertise, policy relevance, public-facing impact, and specific examples of how the work has been used by government agencies and other organizations. :contentReferenceoaicite:1

What this website does well:

  • communicates a clear area of expertise
  • makes policy and public impact visible
  • gives context for why the research matters
  • organizes work across research, awards, media, policy impact, programs, teaching, and talks

Differentiation lesson:
This type of website helps visitors understand why your work matters and where it has had influence. For students with policy, extension, media, data, or public scholarship interests, a website can show dimensions of your work that may not fit neatly on a CV.

Example 3: Jacqueline Rifkin

Jacqueline Rifkin’s website

Use this example to think about branding, clarity, and audience. As you look through the site, notice how the homepage communicates research identity, professional positioning, and the kinds of work the visitor should associate with the scholar.

What to notice:

  • What is emphasized on the homepage?
  • How quickly can you identify the person’s field and research interests?
  • What types of outputs are highlighted?
  • How does the website’s design or tone support the person’s professional identity?

Differentiation lesson:
A website can help you communicate a coherent professional identity. The design does not need to be complicated, but it should help visitors understand what kind of scholar you are becoming.

NoteYour website should have a purpose

A good academic website does not need to be fancy.

It should help people answer a few basic questions:

  • Who are you?
  • What do you study?
  • What are you working on now?
  • What should people read first?
  • How can people contact you?

Once those questions are answered, you can decide what else you want the website to show: teaching materials, policy writing, data projects, media appearances, software, public scholarship, or other work that helps people understand your professional identity.

The tools

Before we start, it helps to establish what tools we’ll be using.

Tool What it does How we use it today
RStudio The program where we edit files and run commands We will open the website project in RStudio
Quarto Turns .qmd files into web pages We will render the website
Git Tracks changes to files over time We will commit changes
GitHub Stores your Git project online We will push the site to GitHub
GitHub Pages Publishes a GitHub repository as a website We will make the site public online

The website structure

The starter repository is a Quarto website. The main files include:

File or folder What it does
_quarto.yml Controls the website title, navigation menu, theme, and publishing settings
index.qmd The homepage
bio.qmd The About page
cv.qmd The CV page
images/ Stores photos and other images
docs/ Stores the rendered website files that GitHub Pages publishes
website.Rproj Opens the project in RStudio

The most important file for the website structure is _quarto.yml.

In this repository, the website is configured to render into the docs/ folder:

project:
  type: website
  output-dir: docs
Tip

GitHub Pages will publish the site from the docs/ folder on the main branch.

Setup

Create a GitHub account

Go to https://github.com.

Click Sign up.

Choose:

  • a username
  • an email address
  • a password

Your username matters because it becomes part of your website address.

For example, if your username is janedoe, your default GitHub Pages website can look like one of these:

https://janedoe.github.io
https://janedoe.github.io/repository-name

For an academic website, choose a username you would be comfortable putting on your CV, job market materials, or research projects.

Install the software

You need four things on your computer:

  1. R
  2. RStudio
  3. Quarto
  4. Git

Download them here:

Software Link
R https://cran.r-project.org/
RStudio Desktop https://posit.co/download/rstudio-desktop/
Quarto https://quarto.org/docs/get-started/
Git https://git-scm.com/downloads

Open RStudio.

Go to:

Tools > Global Options > Git/SVN

If RStudio sees Git, you should see a path to a Git executable.

On Windows, it may look something like:

C:/Program Files/Git/bin/git.exe

Create your website repository

Go to the starter repository:

https://github.com/laurenchenarides/website

Click Fork.

TipWhat does it mean to fork a repository?

A fork is your own copy of someone else’s GitHub repository.

For this lab, you will fork my website repository. That means GitHub will create a copy of my website files inside your own GitHub account. You are not editing my website. You are creating your own version that you can change.

After you fork the repository, you can replace my content with yours. For example, you can change:

  • the site title
  • the About page
  • your photo
  • your research interests
  • your teaching page
  • your CV
  • the colors and layout

By the end of the lab, your website should start looking like your academic website, not mine. My repository is just the starting structure.

Change the repository name if needed.

Change the description.

Leave “Copy the main branch only” selected.

Click Create fork.

ImportantPublic vs. private

The default option after forking a public repository is to keep it public. You can change the repository visibility by going into the Settings.

GitHub Pages websites are intended to be visible online. Do not put private information, sensitive data, unpublished datasets, passwords, API keys, or confidential files in this repository.

Open the project in RStudio

You need a way for RStudio to talk to GitHub.

The easiest beginner-friendly workflow is:

  1. Use GitHub to create the repository.
  2. Use RStudio to clone the repository.
  3. Use RStudio’s Git tab to commit and push changes.
NoteForking and cloning are different steps

In this lab, you will do two different things with the repository.

Forking happens on GitHub. When you fork my repository, GitHub creates your own copy of the website repository inside your GitHub account. This is the version of the website that you will edit and eventually publish.

Cloning happens in RStudio. When you clone your forked repository, RStudio downloads a copy of your GitHub repository onto your computer. This lets you edit the website files locally, render the site, and send your changes back to GitHub.

Put simply:

  • Fork = make your own copy on GitHub
  • Clone = download your GitHub copy to your computer

You fork the repository once. You clone it once on each computer where you want to work on the website.

Copy your repository URL

Go to your new GitHub repository.

Click the green Code button.

Copy the HTTPS URL.

It will look like this:

https://github.com/username/username.github.io.git

or:

https://github.com/username/website.git

Clone the repository in RStudio

Open RStudio.

Go to:

File > New Project > Version Control > Git

Paste your repository URL into Repository URL.

Choose where the project should live on your computer.

Click Create Project.

RStudio will download the website files and open the project.

Edit and preview the site

Preview the website

In RStudio, open the file:

index.qmd

This is the homepage.

Now preview the website.

In RStudio, look for the Build tab.

Click:

Render Website

If that works, RStudio will render the Quarto website.

You can also run this command in the Terminal tab:

quarto render

The rendered website files will appear in the docs/ folder.

You edit the .qmd files.

Quarto creates the .html files.

For example:

You edit Quarto creates
index.qmd docs/index.html
bio.qmd docs/bio.html
cv.qmd docs/cv.html

Customize the homepage

Open:

index.qmd

Find the title and homepage text.

Replace the existing information with your own.

For example:

---
title: "Your Name"
image: "images/photo.png"
execute:
  echo: false
  warning: false
about:
  template: trestles
  links:
    - icon: github
      href: https://github.com/yourusername
    - icon: linkedin
      href: https://www.linkedin.com/in/yourname/
---

### Welcome!

I am a PhD student in economics. My research interests include labor economics, public economics, industrial organization, and applied econometrics.

This website includes my research, teaching, CV, and contact information.

Edit the text so that it sounds like you.

You do not need to sound overly polished. A simple first version is fine.

Use three short parts:

  1. Who you are
  2. What you study
  3. What people can find on your site

Example:

I am a PhD student in economics at [University]. I study [field/topic]. This site includes my research, teaching materials, CV, and contact information.

Add or replace your photo

Put your photo in the images/ folder.

A simple filename is best:

photo.png

or:

headshot.jpg

Then update the image line in index.qmd:

image: "images/headshot.jpg"

Render the website again.

quarto render

Check that the image appears.

These are different filenames:

Headshot.jpg
headshot.jpg
headshot.JPG

Use simple lowercase filenames with no spaces.

Customize the navigation menu

Open:

_quarto.yml

Look for the section that controls the navigation bar.

It will look something like this:

website:
  title: "your-site-title"
  navbar:
    right:
      - text: "About"
        href: bio.qmd
      - text: "CV"
        href: cv.qmd

You can add, remove, or rename pages.

For a PhD student website, a good starter menu is:

website:
  title: "Your Name"
  navbar:
    right:
      - text: "About"
        href: bio.qmd
      - text: "Research"
        href: research.qmd
      - text: "Teaching"
        href: teaching.qmd
      - text: "CV"
        href: cv.qmd

If you add a page to the menu, you also need to create the matching .qmd file.

For example, if you add:

- text: "Research"
  href: research.qmd

then create a file named:

research.qmd

Create a research page

In RStudio, create a new file:

File > New File > Quarto Document

Save it as:

research.qmd

You can start with this:

---
title: "Research"
---

## Research interests

I am interested in:

- Topic 1
- Topic 2
- Topic 3

## Working papers

### Paper title

Brief description of the paper.

**Status:** In progress.

## Publications

Add publications here as they become available.

Render the website again:

quarto render

Save and publish changes

Commit and push

Now we need to send your changes back to GitHub.

In RStudio, open the Git tab.

You should see a list of changed files.

Check the boxes next to the files you changed.

Click Commit.

Write a short commit message.

Examples:

Customize homepage
Add research page
Update CV page

Click Commit.

Then click Push.

A commit is a saved checkpoint in your project history.

A good commit message briefly says what changed.

A push sends your committed changes from your computer to GitHub.

Publish with GitHub Pages

Go to your repository on GitHub.

Click Settings.

In the left menu, click Pages.

Under Build and deployment, choose:

  • Source: Deploy from a branch
  • Branch: main
  • Folder: /docs

Click Save.

GitHub will publish the website.

The first publication can take a few minutes.

Your site will usually appear at one of these addresses:

https://username.github.io

or:

https://username.github.io/repository-name
ImportantWhy do we choose /docs?

This Quarto website renders the finished HTML files into the docs/ folder.

GitHub Pages needs to know where the finished website files are.

For this project, the answer is:

main branch / docs folder

Check your website

After GitHub Pages finishes publishing, open your website in a browser.

Check:

  • Does the homepage load?
  • Does your photo show up?
  • Do the navigation links work?
  • Does the CV page open?
  • Does the research page open?
  • Are there any old links or names that still need to be replaced?

If something is wrong, go back to RStudio, edit the file, render again, commit, and push.

That is the basic cycle:

Edit -> Render -> Commit -> Push -> Check website

Common errors and fixes

My website still shows the old version

Try these steps:

  1. Wait a minute and refresh the page.
  2. Make sure you pushed your changes.
  3. Make sure you rendered the website before committing.
  4. Make sure GitHub Pages is publishing from main and /docs.

My image does not show up

Check:

  1. Is the image in the images/ folder?
  2. Does the filename match exactly?
  3. Did you render the website after adding the image?
  4. Did you commit and push the image file?

My navigation link is broken

Check:

  1. Does the .qmd file exist?
  2. Is the filename spelled the same way in _quarto.yml?
  3. Did you render the website after editing _quarto.yml?

RStudio asks me to log in to GitHub

This is normal.

Follow the login prompts.

If RStudio cannot authenticate, use GitHub’s instructions for connecting Git to GitHub, or ask for help during the lab.

GitHub Pages says the site is not published

Check:

  1. Is the repository public?
  2. Is the source set to Deploy from a branch?
  3. Is the branch set to main?
  4. Is the folder set to /docs?
  5. Does the docs/ folder contain an index.html file?
TipBest case scenario

The minimum successful outcome is:

  1. The student has their own repository.
  2. The repository opens in RStudio.
  3. The student changes the homepage.
  4. The student commits and pushes the change.

Publishing with GitHub Pages can be completed at the end or immediately after class.

After the workshop

After the first version is online, improve the website one page at a time.

Suggested pages:

Page What to include
About Short bio, research interests, education
Research Working papers, publications, projects
Teaching Courses taught, teaching interests
CV Link to a PDF CV
Contact Email, office, GitHub, Google Scholar, LinkedIn

Before sharing your website, check:

Optional: Add your CV

Save your CV as:

cv.pdf

Put it in the main project folder.

Then link to it from cv.qmd:

---
title: "CV"
---

You can download my CV [here](cv.pdf).

Render, commit, and push.

Optional: Use a custom domain later

You do not need a custom domain for this lab.

The free GitHub Pages address is enough to get started.

Later, you can connect a custom domain such as:

yourname.com

or:

yourname.org

For today, focus on publishing the site with the default GitHub Pages address.

Final workflow

Every time you update your website, use the same workflow:

1. Edit the .qmd files in RStudio
2. Render the website
3. Look at the preview
4. Commit the changed files
5. Push to GitHub
6. Check the live website

That is the foundation of a reproducible website workflow.