Publishing Website with Quarto and Github

Why Quarto websites?

Static websites: simple, fast, free.

Quarto advantage: integrates text, code, and publishing.

GitHub Pages: free hosting for version-controlled sites.

Local Quarto Website

We will first get two types of minimal websites running locally (i.e. stored on your computer). We will use R, Quarto, Git, and Github - tools which we have mastered in last one month.

Starting Website Project

  1. File > New Project… > New Directory > Quarto Website

  2. Name it mysite.

  3. Click Create Project.

RStudio opens your new project. You should see files like:

  1. _quarto.yml (site configuration): This is the default configuration file with the site metadata including options about looks and navigation.

  2. index.qmd (homepage): Landing Page. Never rename this file

  3. about.qmd (About page)

  4. styles.css (optional, template dependent)

  5. mysite.Rproj (the R Project file)

More detailed description of various elements is here

Basic Modifications
  1. In _quarto.yaml, change the title to your name. What each section means (quick explainer)

project.type: must be website for multi-page sites.

website.title: site title in the navbar and browser tab.

website.navbar.left: list of pages shown as left-side nav links.

(Use either href: about.qmd or { text: “About”, href: about.qmd }.)

format.html: page rendering options (theme, TOC, numbering, etc.)

  1. In _quarto.yaml, add output-dir: docs under type: website. This is needed for hosting on Github which we will do in later steps.
project:
  type: website
  output-dir: docs

  1. Create a file named .nojekyll in your repository’s root directory (i,e mysite/), which is required to disable some processing of HTML files that GitHub does by default. From RStudio’s Files pane, click New Blank File > Text File, then type .nojekyll > click OK (you can use the Text File option to create any file type)

  2. Open index.qmd. Delete the existing content. Paste the following code and make suitable modifications. Then save.

---
title: "<Your Name>"
---

I am a Ph.D. student in Government at [Georgetown University](https://government.georgetown.edu/), specializing in Comparative Politics and Political Methodology. My dissertation examines how property rights—conceptualized as symbolic, consumptive, and productive rights—shape individuals’ political strategies and political behavior, with a regional focus on India. Methodologically, I combine formal theory, fieldwork, and advanced quantitative approaches, including causal inference, spatial analysis, and Bayesian hierarchical modeling.

In addition to my research, I am deeply committed to teaching and mentoring. I have extensive experience as a teaching assistant for graduate-level courses in quantitative methods and co-lead initiatives such as Math Camp and the Methods Brown Bag series, which broaden methodological training in the department. I also design reproducible, digital-first research and teaching materials using Quarto, GitHub, and open-source workflows, reflecting my commitment to accessible, transparent scholarship.

Outside of academia, I enjoy exploring cooking science and photography.
  1. Click Render on top. You should be able to see minimal functional version of your first website.

Now you have a basic version of your website. Let’s start building more.

Replace the YAML in index.qmd with the following:

---
title: "<Your Name>"
image: pp.png # Put your in the root folder and change the file name here
toc: false
about: 
  template: jolla # Change this to text on your card
  image-shape: round
  image-width: 17em
  links:
    - text: LinkedIn
      href: https://www.linkedin.com/in/parushya/ # Change
    - text: GitHub
      href: https://github.com/parushya # Change
    - text: Email
      href: pp714@georgetown.edu # Change
---

Make modifications. Various paramters are explained below:

template: choose from Quarto’s built-in template options. See a full list here

image: supply it the file path to your photo with the correct file extension (png/jpeg/webp)

image-width & image-shape: adjust your image’s size and shape (round, rounded, rectangle)

links: add buttons with links to your social media pages

Press Render

Modifying/Adding Pages

As a default, Quarto website project, creates two html pages corresponding to index.qmd and about.qmd. You can modify the existing pages by changing the content/code in them, as explained above. You can change the name of the page as it appears in the top title bar by changing the following in the _quarto.yaml. Or create a new page (for eg, research.qmd, and save it in root folder), and add it as shown below.

project:
  type: website
  output-dir: docs

website:
  title: "<your name>"
  navbar:
   left:
     - href: index.qmd
       text: Home
     - about.qmd # Delete if you do not want to render it in final page
     - href: research.qmd # Name of the new qmd file after you have created and saved it in the root folder
       text: Research
       

format:
  html:
    theme: cosmo
    css: styles.css

Always, run quarto render in terminal, to build the complete website, after each step

Hosting on Github

We already know how to use Github. The website we created can be easily hosted using same steps with some additions.

  1. Make a new repository on Github.com after logging in. Name it mysite (same as your local project).

  2. Copy the code under …or create a new repository on the command line. Paste it in terminal at the bottom of Rstudio, and run. This should intialize your local git repo and link it to newly created online repo.

  3. Use git add docs, git commit -m "First website", and git push sequentially to put the rendered html files in docs folder to the online repo.

  4. On Github.com, refresh the mysite repository page. You should be able to see docs folder and a readme file uploaded.

  5. Go to Settings > Pages.

  6. Under Build and Deployment set branch to main and folder to docs. Save. Wait a couple of minutes.

  1. You website should be available publicly. Its url would be <your-github-username>.github.io/mysite.

Review of Workflow

  1. Start quarto website R Project

  2. Change output-dir to docs in _quarto.yaml.

  3. Make modifications to individual qmd files, and then in yaml. Do not forget to render by using quarto render in terminal

  4. Make online repo with same project name. Sync by pasting code from instructions on the online repo page into the terminal.

  5. Use git add, commit -m, and push commands to push docs folder to online Github repo.

  6. Go to Settings>Pages, and change deployment folder to docs. Hit Save.

  7. Website is ready in a couple of minutes.

Additional Resource

  1. Quarto Official Documentation for websites.

  2. Quarto Documentation for Books (in html, pdf, and word format). This website is built using the book functionality. It would be particularly useful when it comes to teaching or writing a dissertation manuscript.

  3. Sam Shanny-Csik’s tutorial on creating and modifying quarto websites.

  4. Gallery of websites, prsentations, books, dashboards and interactive docs built with quarto. Use this for inspiration.