Publishing

Session 6

Saturday, the 7th of February, 2026

Mickaël CANOUIL, Ph.D.

Independent Contractor

Updated: Saturday, the 7th of February, 2026

Session Overview

Session 6: Publishing

• Publishing Options Overview
  • Comparison of Quarto Pub, GitHub Pages, Netlify, and other hosting services.
  • Understanding benefits and limitations of each platform.
  • Choosing the right publishing method for different use cases.

• Quarto Pub and GitHub Pages
  • Step-by-step Quarto Pub deployment workflow.
  • Three methods for GitHub Pages: docs folder, quarto publish, and GitHub Actions.
  • Understanding _publish.yml and repository configuration.

• Code Execution Strategies
  • Local execution with freeze vs CI execution.
  • Environment management and dependency handling.
  • Version control best practices for published projects.

• Advanced Topics
  • Custom domains configuration.
  • Automated deployment workflows.
  • Troubleshooting common publishing issues.

• Publishing Options Overview
  • Comparison of Quarto Pub, GitHub Pages, Netlify, and other hosting services.
  • Understanding benefits and limitations of each platform.
  • Choosing the right publishing method for different use cases.

• Quarto Pub and GitHub Pages
  • Step-by-step Quarto Pub deployment workflow.
  • Three methods for GitHub Pages: docs folder, quarto publish, and GitHub Actions.
  • Understanding _publish.yml and repository configuration.

• Code Execution Strategies
  • Local execution with freeze vs CI execution.
  • Environment management and dependency handling.
  • Version control best practices for published projects.

• Advanced Topics
  • Custom domains configuration.
  • Automated deployment workflows.
  • Troubleshooting common publishing issues.

Session Objectives

This session explores comprehensive publishing strategies for Quarto projects, covering multiple deployment platforms, automation workflows, and best practices for different use cases.

Learning Objectives

By the end of this session, participants will be able to:

• Choose the right publishing method for your use case.
• Deploy a Quarto project to multiple platforms.
• Set up automated publishing workflows.
• Troubleshoot common publishing issues.
• Configure custom domains and advanced features.
• Distribute extensions via GitHub or archives.

Quarto Publishing

Publishing Options Overview

Service	Best For	Key Features
Quarto Pub	Public content, getting started	Free, simple, 100MB limit
GitHub Pages	Open source projects	Git integration, custom domains
Netlify	Professional sites	Advanced features, previews
Posit Connect	Enterprise/organisations	Security, authentication
Other Services	Custom requirements	Firebase, S3, self-hosted

TipRule of thumb

Start with Quarto Pub for learning, use GitHub Pages for projects, Netlify for production sites

Quarto Pub

Your First Quarto Pub Deployment

1. Create an account.
   Visit quartopub.com and sign up.

2. Publish from CLI.

   bash

   quarto publish quarto-pub

3. Authenticate.

   • Browser opens for authorization
   • Confirm publishing permissions
   • Site deploys automatically!

NoteThat’s it!

Your site is live at https://username.quarto.pub/project-name.

Understanding _publish.yml

Created automatically when you first publish:

_publish.yml

- source: project
  quarto-pub:
    - id: "abc123-def456-ghi789"
      url: "https://myusername.quarto.pub/myproject"

• Safe for version control (no credentials).
• Shareable across team members.
• Service configuration stored locally.
• Reusable for subsequent deployments.

Hands-On Exercise: Quarto Pub

Exercise Overview

Objective: Publish the branded project you created in Session 5 using Quarto Pub.

Example Code (reused from Session 5): Exercises

bash

tar -xzf "05b-exercises.tar.gz" -C "06-publishing"

Publishing to Quarto Pub

1. Create a simple Quarto document.
2. Add some content (text, code, plots).
3. Run quarto publish quarto-pub.
4. Share your live URL with a neighbour.

bash

# Publish without prompts
quarto publish quarto-pub --no-prompt

# Publish without opening browser
quarto publish quarto-pub --no-browser

# Publish without re-rendering
quarto publish quarto-pub --no-render

Success Criteria

✅ You’ve successfully completed the exercise if you can:

• Successfully publish your Quarto project to Quarto Pub.

GitHub Pages

Three Ways to Use GitHub Pages

Render to docs/

• Simplest approach
• Commit rendered output
• Good for small projects

quarto publish

• Local rendering
• Automatic deployment
• Clean separation

 

GitHub Actions

• Fully automated
• Triggered by commits
• Most professional

 

Method 1: Render to docs/

• Configure Output Directory

  yaml

  # _quarto.yml
  project:
    type: website
    output-dir: docs

• Add .nojekyll File

  bash

  touch .nojekyll

• Render and Push

  bash

  quarto render
  git add .
  git commit -m "feat: Add rendered site"
  git push

• Configure Repository

  Settings → Pages → Source: Deploy from branch → Branch: main → Folder: /docs

Method 2: quarto publish gh-pages

• Setup Source Branch

  bash

  # Create gh-pages branch
  git checkout --orphan gh-pages
  git rm -rf .
  git commit --allow-empty -m "chore: Initial gh-pages commit"
  git push origin gh-pages
  git checkout main

• Configure .gitignore

  txt

  _site/
  _book/

• Publish

  bash

  quarto publish gh-pages

Method 3: GitHub Actions Workflow

• Create Workflow File: .github/workflows/publish.yml.

  yaml

  name: Quarto Publish
  on:
    workflow_dispatch:
    push:
      branches: main
  
  jobs:
    build-deploy:
      runs-on: ubuntu-latest
      permissions:
        contents: write
      steps:
        - name: Check out repository
          uses: actions/checkout@v4
  
        - name: Set up Quarto
          uses: quarto-dev/quarto-actions/setup@v2
  
        - name: Render and Publish
          uses: quarto-dev/quarto-actions/publish@v2
          with:
            target: gh-pages
          env:
            GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Hands-On Exercise: GitHub Pages

Exercise Overview

Objective: Publish the branded project you created in Session 5 using GitHub Pages.

Example Code (reused from Session 5): Exercises

bash

tar -xzf "05b-exercises.tar.gz" -C "06-publishing"

Publishing to GitHub Pages

Choose one method and deploy your project:

Method 1: docs/ folder

1. Modify _quarto.yml.
2. Add .nojekyll.
3. Render and push.
4. Configure in GitHub settings.

Method 2: quarto publish

1. Setup gh-pages branch.
2. Update .gitignore.
3. Run quarto publish gh-pages.
4. Verify deployment.

Success Criteria

✅ You’ve successfully completed the exercise if you can:

• Successfully publish your Quarto project to GitHub Pages using one of the methods.

Code Execution Strategies

The Big Decision: Where to Execute Code?

Local Execution + Freeze

_quarto.yml

execute:
  freeze: auto

Pros:

• Faster CI builds.
• Consistent environment.
• Handle legacy code.

Cons:

• Manual re-execution needed.
• Larger repository size.

CI Execution

Pros:

• Always fresh execution.
• Smaller repositories.
• Reproducible environments.

Cons:

• Longer build times.
• Dependency management.
• Potential CI failures.

Freeze Strategy Implementation

• Enable Freezing

  _quarto.yml

  execute:
    freeze: auto

• Re-render Locally

  bash

  quarto render

• Version Control

  bash

  git add _freeze/
  git commit -m "chore: Update frozen computations"
  git push

Important

The _freeze/ directory stores computational results and must be committed to Git.

CI Execution with Dependencies

Python/Jupyter Example

yaml

- name: Install Python and Dependencies
  uses: actions/setup-python@v5
  with:
    python-version: '3.13'
    cache: 'pip'

- name: Install Jupyter
  run: pip install jupyter

- name: Install Requirements
  run: pip install -r requirements.txt

R/Knitr Example

yaml

- name: Install R
  uses: r-lib/actions/setup-r@v2
  with:
    r-version: '4.5.0'

- name: Install R Dependencies
  uses: r-lib/actions/setup-renv@v2
  with:
    cache-version: 1

Version Control Strategies

Use a freeze strategy (recommended):

yaml

execute:
  freeze: auto

Commit to Git:

• Source files (.qmd).
• _freeze/ directory.
• Configuration files.

Don’t Commit:

• _site/, _book/, or _manuscript/.
• Temporary files.
• Local dependencies.

Environment Management

Use a tool to manage your R , Python , or Julia environment:

• renv for R.
• uv, pip, or conda for Python.
• Pkg for Julia.

Advanced Topics

Custom Domains

GitHub Pages Custom Domain

1. Add CNAME file to project root:

   txt

   yourdomain.com

2. Configure DNS records:

   • Apex domain: A records to GitHub IPs.
   • Subdomain: CNAME to username.github.io.

3. Enable in repository settings.

Netlify Custom Domain

• Automatic HTTPS.
• Easy DNS management.
• Domain purchasing available.

Extension Distribution

Distribution Methods

GitHub Distribution (Recommended)

bash

# Users install with:
quarto add yourorg/company-report

# Or specific version/tag:
quarto add yourorg/company-report@v1.0.0

# Or from branch:
quarto add yourorg/company-report@main

Benefits: Version control, easy updates, namespace management (yourorg/extension).

Archive Distribution

bash

# From URL:
quarto add https://example.com/company-report.zip

# From local file:
quarto add ./company-report.tar.gz

Benefits: No GitHub required, works offline, controlled distribution.

Publishing Best Practices

Prepare your extension:

1. Add README.md - Installation instructions and documentation.
2. Include LICENSE - Specify usage terms.
3. Create example.qmd - Demonstrate usage.
4. Version with tags - Use semantic versioning (e.g., v1.0.0).

Tip

See Distributing Extensions for complete details.

Copyright

© 2026 Mickaël CANOUIL