Deploying a Quarto Site to GitHub Pages

Complete guide to deploying Quarto documentation to GitHub Pages with automated workflows

This appendix provides a comprehensive guide to deploying your Quarto documentation site to GitHub Pages, including setup, configuration, and automated deployment workflows.

📋 Table of Contents

• 📖 Overview
• ✅ Prerequisites
• 🔧 Deployment Methods
• 📁 Method 1: Deploy from /docs Folder
• ⚙️ Method 2: GitHub Actions Deployment
• 🔬 Advanced Configuration
• ⚡ Optimization and Best Practices
• 🔧 Troubleshooting Common Issues
• 📊 Monitoring and Maintenance
• 📈 Performance Metrics
• 🔄 Migration from Other Platforms
• 🎯 Conclusion
• 📚 Additional Resources

📖 Overview

GitHub Pages is GitHub’s free static site hosting service that integrates seamlessly with your repositories.

It’s the most popular and straightforward option for hosting Quarto documentation sites, especially for open-source projects and technical documentation.

Key Benefits

• ✅ Free hosting for public repositories
• ✅ Automatic SSL certificates (HTTPS)
• ✅ Custom domain support
• ✅ Git integration - deploy on every push
• ✅ GitHub Actions automation
• ✅ Built-in CDN for fast global delivery

✅ Prerequisites

Before deploying to GitHub Pages, ensure you have:

• A GitHub repository with your Quarto project
• Quarto installed locally for testing
• Basic understanding of Git and GitHub workflows
• Repository with appropriate permissions (Admin access for settings)

🔧 Deployment Methods

GitHub Pages offers two main deployment approaches for Quarto sites:

Method 1: Deploy from /docs Folder (Recommended for Beginners)

This method renders locally or via GitHub Actions and commits the HTML output to the repository.

Method 2: GitHub Actions Deployment (Recommended for Production)

This method uses GitHub Actions to render and deploy automatically, keeping the repository clean of build artifacts.

📁 Method 1: Deploy from /docs Folder

Step 1: Configure Quarto Output Directory

Update your _quarto.yml to output to the docs/ directory:

project:
  type: website
  output-dir: docs  # GitHub Pages serves from this folder

website:
  title: "Your Documentation Site"
  site-url: "https://username.github.io/repository-name"
  
format:
  html:
    theme: cosmo
    toc: true

Step 2: Configure GitHub Repository Settings

1. Navigate to Repository Settings
   • Go to your GitHub repository
   • Click on “Settings” tab
   • Scroll to “Pages” section in the left sidebar
2. Configure Pages Source
   • Source: Select “Deploy from a branch”
   • Branch: Choose main (or your default branch)
   • Folder: Select /docs
   • Click “Save”

Step 3: Render and Deploy

# Render your Quarto site
quarto render

# Commit the rendered files
git add .
git commit -m "Deploy documentation update"
git push origin main

Step 4: Access Your Site

Your site will be available at:

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

Note: Initial deployment may take 5-10 minutes. Subsequent updates typically deploy within 1-2 minutes.

⚙️ Method 2: GitHub Actions Deployment

Step 1: Create GitHub Actions Workflow

Create .github/workflows/quarto-publish.yml:

name: Render and Deploy Quarto Documentation

on:
  # Trigger on pushes to main branch
  push:
    branches: [main]
  # Allow manual workflow dispatch
  workflow_dispatch:

# Set permissions for GitHub Pages deployment
permissions:
  contents: read
  pages: write
  id-token: write

# Prevent concurrent deployments
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        
      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2
        with:
          # Optionally specify Quarto version
          version: 'release'
          
      - name: Install dependencies
        run: |
          # Add any additional dependencies here
          # pip install -r requirements.txt  # For Python dependencies
          # npm install                      # For Node.js dependencies
          
      - name: Render Quarto project
        run: quarto render
        
      - name: Setup Pages
        uses: actions/configure-pages@v4
        
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: ./docs
          
  deploy:
    needs: build
    runs-on: ubuntu-latest
    
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
      
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v3

Step 2: Configure Repository Settings

1. Navigate to Repository Settings > Pages
2. Source: Select “GitHub Actions”
3. Save the configuration

Step 3: Update Quarto Configuration

Update _quarto.yml for GitHub Actions deployment:

project:
  type: website
  output-dir: docs
  
website:
  title: "Your Documentation Site"
  site-url: "https://username.github.io/repository-name"
  repo-url: "https://github.com/username/repository-name"
  repo-actions: [edit, issue]  # Adds edit/issue links
  
format:
  html:
    theme: cosmo
    toc: true
    anchor-sections: true
    smooth-scroll: true
    link-external-newwindow: true

Step 4: Trigger Deployment

# Push changes to trigger workflow
git add .
git commit -m "Set up GitHub Actions deployment"
git push origin main

The workflow will automatically render and deploy your site.

🔬 Advanced Configuration

Custom Domain Setup

1. Add CNAME file to your repository root:

docs.yoursite.com

2. Configure DNS with your domain provider:
   • Create a CNAME record pointing to username.github.io
   • Or use A records for apex domains
3. Enable Custom Domain in GitHub Pages settings

Environment Variables and Secrets

For sites requiring authentication or API keys:

# Add to your workflow
- name: Render with secrets
  env:
    API_KEY: ${{ secrets.API_KEY }}
  run: quarto render

Conditional Deployment

Deploy only on specific conditions:

# Only deploy from main branch
- name: Deploy to GitHub Pages
  if: github.ref == 'refs/heads/main' && github.event_name == 'push'
  uses: actions/deploy-pages@v3

⚡ Optimization and Best Practices

Performance Optimization

1. Optimize Images

# Add image optimization to workflow
- name: Optimize images
  run: |
    find docs -name "*.png" -o -name "*.jpg" | xargs -I {} convert {} -quality 85 {}

2. Enable Compression

format:
  html:
    minimal: true  # Reduces HTML size
    embed-resources: false  # Don't inline all resources

SEO and Analytics

website:
  google-analytics: "G-XXXXXXXXXX"
  open-graph: true
  twitter-card: true
  
format:
  html:
    html-math-method: katex  # Faster than MathJax
    code-copy: true
    anchor-sections: true

Security Headers

Add a _headers file to your output directory for enhanced security:

/*
  X-Frame-Options: DENY
  X-Content-Type-Options: nosniff
  Referrer-Policy: strict-origin-when-cross-origin
  Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';

🔧 Troubleshooting Common Issues

1. Site Not Updating

Problem: Changes don’t appear on the live site.

Solutions:

# Check GitHub Actions status
# Repository > Actions tab > Look for failed workflows

# Force cache refresh
# Add ?v=timestamp to URLs

# Verify GitHub Pages settings
# Settings > Pages > Ensure correct source/branch

2. Build Failures

Problem: GitHub Actions workflow fails.

Solutions:

# Add debugging to workflow
- name: Debug Quarto
  run: |
    quarto --version
    quarto check
    ls -la
    
# Check for missing dependencies
- name: Install missing dependencies
  run: |
    sudo apt-get update
    sudo apt-get install -y pandoc

3. Broken Links and Images

Problem: Internal links don’t work on GitHub Pages.

Solutions:

# Use relative links in markdown
[Link to page](./other-page.html)  # Good
[Link to page](/other-page.html)   # May break with subdirectories

# Configure site URL properly
website:
  site-url: "https://username.github.io/repository-name"

4. CSS and JavaScript Issues

Problem: Styling or interactive elements don’t work.

Solutions:

# Ensure correct resource paths
format:
  html:
    css: 
      - styles.css
    include-in-header:
      - custom-head.html
    include-after-body:
      - custom-footer.html

📊 Monitoring and Maintenance

Analytics Setup

1. Google Analytics 4

website:
  google-analytics: 
    tracking_id: "G-XXXXXXXXXX"
    anonymize_ip: true

2. GitHub Insights
   • Monitor repository traffic
   • Track popular pages
   • Understand user behavior

Automated Link Checking

Add link checking to your workflow:

- name: Check links
  run: |
    npm install -g markdown-link-check
    find . -name "*.md" -exec markdown-link-check {} \;

Content Updates

Set up automated dependency updates:

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

📈 Performance Metrics

Monitor your site’s performance:

• Core Web Vitals: Use Google PageSpeed Insights
• Load Times: Monitor with GitHub Pages analytics
• SEO: Check with Google Search Console

🔄 Migration from Other Platforms

From GitBook

1. Export content as Markdown
2. Adjust image paths and links
3. Convert GitBook-specific syntax to Quarto

From Jekyll

1. Convert _config.yml to _quarto.yml
2. Update Liquid tags to Quarto shortcodes
3. Adjust layout templates

From Sphinx

1. Convert reStructuredText to Markdown
2. Update cross-references to Quarto syntax
3. Migrate custom extensions

🎯 Conclusion

GitHub Pages provides an excellent, free hosting solution for Quarto documentation sites. The combination of automated deployment via GitHub Actions, built-in SSL, and seamless Git integration makes it ideal for:

• Open source project documentation
• Technical blogs and knowledge bases
• Team documentation sites
• Personal portfolios and research publications

Choose Method 1 (deploy from /docs) for simple sites with infrequent updates, or Method 2 (GitHub Actions) for production sites requiring automated deployment, preprocessing, or complex build steps.

📚 Additional Resources

• GitHub Pages Documentation
• Quarto GitHub Actions
• GitHub Pages Custom Domains
• GitHub Actions Documentation