Deploy Quarto Presentations to GitHub Pages

This guide provides step-by-step instructions for creating and hosting Quarto presentations on GitHub Pages.

Prerequisites

• Quarto installed on your system
• Git repository with your presentation files
• GitHub account

Project Structure

Your project should have this structure:

your-presentation/
├── presentation.qmd          # Your main presentation file
├── _quarto.yml              # Quarto configuration
├── assets/                  # Images, videos, etc.
│   ├── image1.png
│   ├── video1.mp4
│   └── ...
└── docs/                    # Generated output (created by Quarto)
    ├── index.html
    ├── presentation.html
    └── ...

Step 1: Create Quarto Configuration File

Create a _quarto.yml file in your project root:

project:
  type: website
  output-dir: docs

website:
  title: "Your Presentation Title"
  site-url: "https://your-username.github.io/your-repo-name"
  
format:
  html:
    theme: default

Replace:

• Your Presentation Title with your actual presentation title
• your-username with your GitHub username
• your-repo-name with your repository name

Step 2: Create Your Presentation

Create a .qmd file (e.g., presentation.qmd) with your content:

---
title: "Your Presentation Title"
subtitle: "Your Subtitle"
author: "Your Name"
date: "2025-07-29"
format: 
  revealjs:
    theme: default
    slide-number: true
    chalkboard: true
    logo: your-logo.png
    footer: "Your Footer Text"
    title-slide-attributes:
      data-background-image: "background.svg"
      data-background-size: "auto"
      data-background-opacity: "0.3"
      data-background-position: "bottom"
---

## Slide 1
Your content here

## Slide 2
More content here

Step 3: Render Your Presentation

Run the following command in your project directory:

quarto render

This will:

• Generate HTML files in the docs/ directory
• Copy all assets (images, videos) to the output directory
• Create an index.html file for GitHub Pages

Step 4: Initialize Git Repository (if not already done)

git init
git add .
git commit -m "Initial commit"

Step 5: Push to GitHub

1. Create a new repository on GitHub
2. Add the remote origin:

   git remote add origin https://github.com/your-username/your-repo-name.git
   

3. Push your code:

   git push -u origin main
   

Step 6: Configure GitHub Pages

1. Go to your GitHub repository: https://github.com/your-username/your-repo-name
2. Click on “Settings” tab
3. Scroll down to “Pages” in the left sidebar
4. Under “Source”, select:
   • Source: “Deploy from a branch”
   • Branch: “main”
   • Folder: “/ (docs)”
5. Click “Save”

Step 7: Access Your Presentation

After a few minutes, your presentation will be available at:

• Main site: https://your-username.github.io/your-repo-name/
• Direct link: https://your-username.github.io/your-repo-name/presentation.html

Automatic Updates

To update your presentation:

1. Edit your .qmd file
2. Re-render: quarto render
3. Commit and push changes:

   git add .
   git commit -m "Update presentation"
   git push origin main
   

GitHub Pages will automatically update your site within a few minutes.

Troubleshooting

Common Issues

1. 404 Error:
   • Check that GitHub Pages is configured to serve from the correct branch and folder
   • Ensure index.html exists in the docs/ directory
2. Missing Assets:
   • Verify that all images/videos are in the correct relative paths
   • Check that Quarto copied all assets to the docs/ directory
3. Site Not Updating:
   • Wait a few minutes for GitHub Pages to update
   • Check the repository’s “Actions” tab for any deployment errors
   • Clear your browser cache
4. Relative Path Issues:
   • Use relative paths for all assets (e.g., ./image.png not /image.png)
   • Ensure the site-url in _quarto.yml matches your GitHub Pages URL

Useful Commands

# Preview locally before deploying
quarto preview

# Render specific file
quarto render presentation.qmd

# Check Quarto version
quarto --version

# Validate Quarto project
quarto check

Resources

• Quarto Documentation
• GitHub Pages Documentation
• RevealJS Documentation
• Quarto Presentations Guide