Publishing

Session 6

Mickaël CANOUIL, Ph.D. ORCID
pro@mickael.canouil.dev

Independent Contractor

Friday, the 10th of April, 2026

Session Overview

Session 6: Publishing

  • Publishing Options Overview
    • Comparison of Posit Connect Cloud, GitHub Pages, Netlify, and other hosting services.
    • Understanding benefits and limitations of each platform.
    • Choosing the right publishing method for different use cases.
  • Posit Connect Cloud and GitHub Pages
    • Step-by-step Posit Connect Cloud 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 & Extension Distribution
    • Custom domains configuration.
    • Extension distribution via GitHub and archives.
    • Publishing best practices for extensions.
  • Publishing Options Overview
    • Comparison of Posit Connect Cloud, GitHub Pages, Netlify, and other hosting services.
    • Understanding benefits and limitations of each platform.
    • Choosing the right publishing method for different use cases.
  • Posit Connect Cloud and GitHub Pages
    • Step-by-step Posit Connect Cloud 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 & Extension Distribution
    • Custom domains configuration.
    • Extension distribution via GitHub and archives.
    • Publishing best practices for extensions.

Session Objectives

This session explores comprehensive publishing strategies for Quarto projects, covering Posit Connect Cloud, GitHub Pages, 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
Posit Connect Cloud Public content, getting started Free tier, simple, Posit account
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

Rule of thumb

Start with Posit Connect Cloud for learning and public content, use GitHub Pages for open source projects, and Netlify or Posit Connect for production sites.

Posit Connect Cloud

Your First Posit Connect Cloud Deployment

  1. Create an account. Visit connect.posit.cloud and sign up for a Posit account.

  1. Publish from CLI.

    bash
    quarto publish posit-connect-cloud

  1. Authenticate.

    • Browser opens for authorisation.
    • Confirm publishing permissions.
    • Site deploys automatically.

That’s it!

Your site is live on Posit Connect Cloud.

Understanding _publish.yml

Created automatically when you first publish:

_publish.yml
- source: project
  posit-connect-cloud:
    - id: "5f3abafe-68f9-4c1d-835b-9d668b892001"
      url: "https://connect.posit.cloud/content/5f3abafe-68f9-4c1d-835b-9d668b892001"
  • Safe for version control (no credentials).
  • Shareable across team members.
  • Service configuration stored locally.
  • Reusable for subsequent deployments.

See Posit Connect Cloud for complete documentation.

Hands-On Exercise: Posit Connect Cloud

Exercise Overview

Objective: Publish the branded website project from Session 5 using Posit Connect Cloud.

Example Code (reused from Session 5): Exercises

bash
tar -xzf "05a-exercises.tar.gz" -C "06-publishing"

Publishing to Posit Connect Cloud

  1. Extract the branded website project.
  2. Preview locally with quarto preview.
  3. Run quarto publish posit-connect-cloud.
  4. Share your live URL with a neighbour.
bash
# Publish without prompts
quarto publish posit-connect-cloud --no-prompt

# Publish without opening browser
quarto publish posit-connect-cloud --no-browser

# Publish without re-rendering
quarto publish posit-connect-cloud --no-render

Success Criteria

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

  • Successfully publish your Quarto project to Posit Connect Cloud.

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@v6

      - 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 website project from Session 5 using GitHub Pages.

Example Code (reused from Session 5): Exercises

bash
tar -xzf "05a-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

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
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

  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.

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

Extension Distribution

Distribution Methods

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).

Distribution Methods

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.

Speaker photo

Mickaël CANOUIL, Ph.D. ORCID

Independent Contractor

pro@mickael.canouil.dev