Using Quarto

azure

best-practices

Using Quarto with GitHub Pages for Documentation

Author

Dario Airoldi

Published

July 2, 2025

Modified

November 3, 2025

📋 Table of Contents

📖 Overview
💡 Key Concepts
🚀 Deploying the Quarto Site
✅ Best Practices
🚀 Advanced Features
🔧 Troubleshooting Common Issues
📊 Monitoring and Maintenance
🎯 Conclusion
📚 References
📑 APPENDIXES

📖 Overview

Quarto is a powerful, open-source scientific and technical publishing system that allows you to create beautiful documentation websites from Markdown files.
When combined with modern hosting platforms, it provides an excellent solution for publishing and maintaining project documentation.

💡 Key Concepts

1. Project Structure

Quarto is highly flexible and supports multiple project structures.

Here are several common approaches:

Standard Documentation Structure

A typical Quarto documentation project follows this structure:

your-repo/
├── src/
│   └── doc/           # Source markdown files
│       ├── index.md
│       ├── guide.md
│       └── reference.md
├── docs/              # Rendered HTML output (for GitHub Pages)
├── _quarto.yml        # Quarto configuration file
└── .github/
    └── workflows/
        └── quarto-publish.yml  # GitHub Actions workflow

Root-Level Structure

For simpler projects, you can place content directly in the root:

your-repo/
├── index.md           # Homepage
├── guide.md           # Documentation pages
├── reference.md
├── about.md
├── docs/              # Rendered output
├── _quarto.yml        # Configuration
└── images/            # Assets

Learn Repository Structure Example

For a repository like your “Learn” repo with existing folder structure, you could adapt it as follows:

Learn/                              # Your existing repository
├── index.md                        # New: Main landing page
├── _quarto.yml                     # New: Quarto configuration
├── docs/                           # New: Rendered output
├── 202506 Build 2025/              # Existing: Event documentation
│   ├── index.md                    # New: Build 2025 overview
│   ├── BRK106/
│   │   └── *.md                    # Existing: Session notes
│   └── BRK122/
│       └── *.md                    # Existing: Session notes
├── 20250702 Azure Naming conventions/  # Existing: Topic folder
│   └── *.md                        # Existing: Content
├── 20250704 TableStorageAccess options/  # Existing: Topic folder
│   └── *.md                        # Existing: Content
└── _ISSUES/                        # Existing: Issue tracking
    └── */                          # Existing: Issue folders

Multi-Section Structure

For larger documentation sites with distinct sections:

your-repo/
├── index.md
├── _quarto.yml
├── docs/              # Rendered output
├── tutorials/         # Tutorial section
│   ├── index.md
│   ├── getting-started.md
│   └── advanced.md
├── reference/         # Reference section
│   ├── index.md
│   ├── api.md
│   └── cli.md
├── blog/              # Blog section (optional)
│   ├── index.md
│   └── posts/
└── assets/            # Shared resources
    ├── images/
    └── styles/

2. Configuration File (`_quarto.yml`)

The _quarto.yml file is the heart of your Quarto project configuration:

project:
  type: website
  output-dir: docs

website:
  title: "Your Documentation"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: guide.qmd
        text: Guide
      - href: reference.qmd
        text: Reference

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

3. Source Directory (`src/doc/`)

Purpose: Contains your source Markdown (.md) or Quarto Markdown (.qmd) files
Best Practices:
- Use clear, descriptive filenames
- Organize content hierarchically with subdirectories
- Include an index.md as your homepage
- Use consistent front matter (YAML headers)

4. Output Directory (`docs/`)

Purpose: Contains the rendered HTML files that hosting platforms will serve
Important Notes:
- This directory is generated by Quarto’s rendering process
- Should be included in your repository for some hosting platforms
- Configure your hosting platform to serve from the appropriate directory

🚀 Deploying the Quarto Site

Quarto sites can be deployed to multiple hosting platforms, each offering different advantages depending on your needs, budget, and infrastructure requirements.

Popular Deployment Targets

1. GitHub Pages (Most Common & Easiest)

✅ Free for public repositories
✅ Automatic SSL and custom domains
✅ Integrated with Git workflow
✅ Zero configuration required
⚠️ Limited to static sites only
⚠️ 1GB storage limit

Best for: Open source projects, personal sites, simple documentation

2. Azure Storage Account Static Websites (Enterprise & Scalable)

✅ Cost-effective pay-as-you-use pricing
✅ Global CDN integration
✅ Enterprise security features
✅ Unlimited storage and bandwidth
✅ Advanced analytics and monitoring
⚠️ Requires Azure subscription
⚠️ More complex setup

Best for: Enterprise documentation, high-traffic sites, multi-environment deployments

3. Other Popular Options

Netlify: Great for modern web workflows with branch previews
Vercel: Excellent performance and developer experience
Firebase Hosting: Good integration with Google services
AWS S3 + CloudFront: Ultimate scalability and control

Choosing the Right Platform

Factor	GitHub Pages	Azure Storage	Netlify	Vercel
Cost	Free	~$1-5/month	Free tier available	Free tier available
Setup Complexity	⭐ Easy	⭐⭐ Medium	⭐ Easy	⭐ Easy
Performance	Good	Excellent	Excellent	Excellent
Custom Domains	✅	✅	✅	✅
Branch Previews	❌	❌	✅	✅
Enterprise Features	Limited	✅	✅	✅

Quick Start Deployment

For most users, we recommend starting with GitHub Pages due to its simplicity:

Configure _quarto.yml:

project:
  type: website
  output-dir: docs

Enable GitHub Pages in repository settings
Push changes - automatic deployment via GitHub Actions

For detailed deployment instructions, see the specific appendixes below.

✅ Best Practices

1. Content Organization

Logical Structure: Organize content by topic or user journey
Navigation: Use clear, hierarchical navigation in your _quarto.yml
Cross-References: Leverage Quarto’s cross-referencing capabilities
Index Pages: Create overview pages for each section

2. Writing Guidelines

Front Matter: Use YAML front matter for metadata:

---
title: "Page Title"
description: "Brief description"
date: "2025-01-14"
---

Code Blocks: Use syntax highlighting and proper language specification
Images: Store images in organized subdirectories, use relative paths
Links: Use relative links for internal navigation

3. Development Workflow

Write: Create/edit Markdown files in your source directory
Preview: Use quarto preview for local development
Render: Run quarto render to generate HTML
Deploy: Push changes to trigger automated deployment
Monitor: Check deployment status and site performance

4. Version Control Considerations

Include Rendered Files: For GitHub Pages, include the docs/ folder in version control
Ignore Temporary Files: Add to .gitignore:
```
.quarto/
/.quarto/
```
Environment-Specific Configs: Use different _quarto.yml files for different environments

🚀 Advanced Features

1. Themes and Styling

Built-in Themes: Choose from cosmo, flatly, darkly, etc.
Custom CSS: Add custom styling via CSS files
SCSS Variables: Customize theme variables

2. Interactive Content

Code Execution: Embed executable code blocks
Jupyter Notebooks: Include .ipynb files directly
Observable JS: Add interactive visualizations

3. Multi-language Support

Code Highlighting: Support for numerous programming languages
Internationalization: Multi-language documentation support

🔧 Troubleshooting Common Issues

1. GitHub Pages Not Updating

Check that the docs/ folder is being committed
Verify GitHub Pages is configured to serve from /docs
Ensure GitHub Actions workflow is running successfully

2. Broken Links

Use relative paths for internal links
Test all links before publishing
Use Quarto’s link checking capabilities

3. Rendering Errors

Check _quarto.yml syntax
Verify all referenced files exist
Review console output for specific error messages

📊 Monitoring and Maintenance

1. Analytics

Add Google Analytics or similar tracking
Monitor page views and user behavior
Use hosting platform insights for performance metrics

2. Content Updates

Regular review of documentation accuracy
Update dependencies and links
Maintain consistent style and formatting

3. Performance

Optimize images for web delivery
Minimize custom CSS and JavaScript
Monitor page load times and Core Web Vitals

🎯 Conclusion

Quarto provides a powerful, flexible platform for creating professional documentation websites. By following these best practices and understanding the key concepts, you can create maintainable, beautiful documentation that automatically publishes to your chosen hosting platform whenever you update your source files.

The combination of Markdown simplicity, Quarto’s rendering capabilities, and modern hosting platforms makes this an excellent choice for project documentation, technical guides, and knowledge bases.

📚 References

Quarto Official Documentation

The comprehensive official guide to Quarto, covering all features from basic usage to advanced configurations. This is the primary resource for understanding Quarto’s capabilities, syntax, and best practices. Essential for anyone working with Quarto as it provides authoritative information on configuration options, formatting, and troubleshooting.

GitHub Pages Documentation

GitHub’s official documentation for Pages, explaining how to set up, configure, and deploy static websites. Crucial for understanding GitHub Pages limitations, custom domains, HTTPS enforcement, and deployment options. This reference helps ensure proper configuration of the hosting environment for your Quarto documentation.

Quarto GitHub Actions

Official GitHub Actions for automating Quarto workflows, including rendering and deployment. This repository provides ready-to-use workflow templates that integrate seamlessly with GitHub Pages. Essential for setting up continuous integration and deployment pipelines for documentation projects.

Markdown Guide

Comprehensive reference for Markdown syntax and best practices. Since Quarto builds upon Markdown, understanding proper Markdown formatting is fundamental. This guide helps ensure consistent, well-formatted source documents that render correctly across different platforms.

GitHub Actions Documentation

Complete guide to GitHub Actions workflows, syntax, and best practices. Important for customizing automation workflows beyond basic Quarto deployment, including adding testing, link checking, or custom build steps to your documentation pipeline.

Quarto Extensions Gallery

Showcase of community-contributed extensions that add functionality to Quarto. Relevant for discovering ways to enhance documentation with additional features like custom formats, filters, or shortcodes that can improve the presentation and functionality of your documentation.

YAML Specification

Official YAML specification, essential for understanding the syntax used in _quarto.yml configuration files and front matter. Proper YAML formatting is critical for Quarto configuration, and this reference helps prevent syntax errors that can break the build process.

Pandoc Documentation

Pandoc is the underlying document conversion engine that powers Quarto. Understanding Pandoc helps with advanced customization, custom formats, and troubleshooting complex rendering issues. Particularly useful when working with cross-references, citations, or custom output formats.

Git Documentation - .gitignore

Essential for understanding how to properly exclude temporary Quarto files from version control. Proper .gitignore configuration prevents committing build artifacts and temporary files while ensuring the rendered documentation is properly tracked.

GitHub Community Guidelines for Documentation

Best practices for creating maintainable, community-friendly documentation projects. Relevant for establishing contribution guidelines, documentation standards, and collaborative workflows when building documentation as part of open-source projects.

Additional Resources

📑 APPENDIXES

APPENDIX A: Quarto Architecture - How Quarto Works

A deep dive into Quarto’s core architecture, site initialization, page loading, and rendering mechanisms. This fundamental guide explains how Quarto’s static-first approach works, the site initialization process, how pages are loaded and rendered, and the relationship between static content and dynamic features. Essential for understanding the technical foundations of Quarto and how it generates fast, accessible static sites with optional JavaScript enhancement.

APPENDIX B: Quarto Architecture - Monolithic vs. Modular Deployment

A comprehensive analysis of deployment strategies for separating content from navigation infrastructure to enable independent deployment cycles. This strategic guide covers monolithic vs. modular deployment approaches, performance and scalability implications, four specific strategies for modular architecture, and practical recommendations with implementation roadmaps. Essential for understanding when and how to scale Quarto sites while maintaining the benefits of static generation.

APPENDIX C: Quarto.yml Document Structure - Complete Reference Guide

An in-depth technical reference covering every aspect of the _quarto.yml configuration file. This companion article provides detailed explanations of all configuration sections including project settings, website configuration, format options, metadata, engines, filters, and advanced features. Essential for understanding the full capabilities of Quarto configuration and implementing complex documentation setups with custom navigation, themes, and publishing workflows.

APPENDIX D: Quarto Specific Markdown Features - Complete Guide

A comprehensive guide to Quarto’s extended markdown syntax and features that go beyond standard Markdown. This technical reference covers div blocks, CSS styling, grid layouts, callout blocks, interactive elements, and advanced formatting options. Essential for creating rich, interactive documentation with sophisticated layouts, highlighting messages, and custom styling using Quarto’s unique markdown extensions.

APPENDIX E: Quarto Theming and Styling - Complete Guide

An extensive guide to Quarto’s theming and styling capabilities, covering built-in themes, custom CSS integration, SCSS customization, Bootstrap integration, and responsive design. This technical reference includes practical examples of color schemes, typography, layout customization, dark mode support, and brand integration. Essential for creating professionally designed documentation websites that reflect your organization’s visual identity and design standards.

APPENDIX H: Optimizing Quarto Build and Deploy

A comprehensive guide to optimizing Quarto build and deployment processes for better performance, faster builds, and more efficient workflows. This technical reference covers build optimization strategies, deployment pipeline improvements, and performance monitoring techniques.

APPENDIX I: Configuring Your Learn Repository for Quarto

To publish your existing Learn repository with Quarto, you would:

Create a main _quarto.yml configuration:

project:
  type: website
  output-dir: docs

website:
  title: "Dario's Learning Journey"
  description: "Technical learning notes and conference insights"
  
  navbar:
    left:
      - href: index.qmd
        text: Home
      - text: "Build 2025"
        menu:
          - href: "202506 Build 2025/index.qmd"
            text: "Overview"
          - href: "202506 Build 2025/BRK106/index.qmd"
            text: "BRK106: .NET Aspire"
          - href: "202506 Build 2025/BRK122/index.qmd"
            text: "BRK122: ASP.NET Core & Blazor"
      - text: "Azure Topics"
        menu:
          - href: "20250702 Azure Naming conventions/index.qmd"
            text: "Naming Conventions"
          - href: "20250704 TableStorageAccess options/index.qmd"
            text: "Table Storage Access"
          - href: "20250706 CosmosDB Access options/index.qmd"
            text: "CosmosDB Access"
      - text: "Development Tips"
        menu:
          - href: "20250709 Manage GitRepo from commandline/index.qmd"
            text: "Git Command Line"
          - href: "20250711 Use http files for easy and repeatable test/index.qmd"
            text: "HTTP Files Testing"
          - href: "20250712 Use QUARTO doc for Github repos doc/index.qmd"
            text: "Quarto Documentation"

format:
  html:
    theme: cosmo
    toc: true
    toc-depth: 3

Create index pages for each major section to provide navigation and context
Rename existing README.md files to index.qmd in each folder to maintain the same content structure

Key Advantages of Alternative Structures

Preserve Existing Organization: Keep your current folder structure and naming conventions
Gradual Migration: Convert sections one at a time
Flexible Navigation: Create custom navigation that makes sense for your content
Maintain Git History: No need to move files, preserving commit history
SEO Friendly: Each section gets its own landing page with proper metadata

APPENDIX J: Deploying a Quarto Site to GitHub Pages

A comprehensive technical guide covering all aspects of deploying Quarto sites to GitHub Pages. This appendix includes detailed setup instructions, automated deployment workflows, custom domain configuration, troubleshooting common issues, and optimization techniques. Essential for understanding GitHub Actions integration, repository configuration, and best practices for maintaining documentation sites on GitHub’s free hosting platform.

APPENDIX K: Deploying a Quarto Site to Azure Storage Accounts

An enterprise-focused guide to deploying Quarto sites to Azure Storage Account static websites. This technical reference covers Azure infrastructure setup, CDN integration, custom domain configuration, automated CI/CD pipelines, cost optimization, security configuration, and monitoring. Essential for organizations requiring scalable, high-performance documentation hosting with enterprise-grade features and global distribution capabilities.