Quarto: Publishing to GitHub Pages

Publishing Quarto projects to GitHub Pages can seem daunting, but with the right approach, it’s a breeze.
This blog post will walk you through various methods to deploy your Quarto creations, from simple manual steps to automated workflows using GitHub Actions.
By the end, you’ll have the know-how to share your dynamic documents, books, and websites seamlessly with the world.

Let’s dive into the essentials of making your Quarto project live on GitHub Pages.

1 Prerequisites

Important

Before proceeding, ensure you have enabled and configured GitHub Pages for your repository (i.e., https://github.com/<username>/<repository>/settings/pages), see GitHub Pages documentation for more details.

The following methods mostly assume your GitHub repository is public. If your repository is private, you may need to adjust the settings to allow GitHub Pages to access the repository using a personal access token.

You can use the Quarto project created with the quarto create project website command as a demo project to try out the methods described in this guide. This will provide a practical example to follow along with.

2 Manual Method

2.1 Using Quarto CLI

The manual method involves using the Quarto Command Line Interface (CLI) to publish your project. This method is straightforward and requires minimal setup.

quarto publish gh-pages

Check out the Quarto CLI help for more details on the publish command.

quarto publish --help

Note

The gh-pages branch is used to publish to GitHub Pages.

quarto publish gh-pages setups the gh-pages branch, renders your project, and pushes the output to the branch.
You can use the --no-render flag to skip rendering and only push a previously rendered project.

3 Automated Method

Automation can streamline the publishing process and reduce the risk of errors. Here are two automated methods using GitHub Actions.

Important

Ensure you have the necessary permissions to create and manage GitHub Actions workflows in your repository (i.e., https://github.com/<username>/<repository>/settings/actions), see GitHub Actions documentation for more details.

3.1 Quarto Publish GitHub Action

Quarto provides an official GitHub Action that simplifies the publishing process. This action takes care of the entire workflow but requires to use quarto publish gh-pages locally at least once to set up the gh-pages branch.

.github/workflows/deploy.yml

name: Deploy

on:
  workflow_dispatch:
  push:
    branches:
      - main

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions: 
      contents: write
      pages: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install Quarto
        uses: quarto-dev/quarto-actions/setup@v2
        with:
          version: pre-release
      # Add any additional steps as needed, such as installing dependencies
      - name: Build and Deploy
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages

Note

The quarto-dev/quarto-actions GitHub Actions are maintained by the Quarto team.
You can find more information about these actions in the Quarto Actions repository.

3.2 Custom GitHub Actions Workflow

For more control over the publishing process, you can set up a custom GitHub Actions workflow. We’ll discuss two scenarios:

• Deploy from a branch
  Classic Pages experience, where the content is published from a specific branch root or /docs folder.

• GitHub Actions
  Best for using frameworks and customizing your build process.

3.2.1 Deploy From a Branch

You can configure a workflow to publish your Quarto project whenever changes are pushed to a specific branch (e.g., main) and deploy the output to GitHub Pages from a specific folder/branch.

Note

The GitHub Action workflow described in Quarto Publish GitHub Action uses gh-pages root as the source for GitHub Pages.

3.2.1.1 Deploying From the docs Folder (e.g., main Branch)

Using the docs folder as the source for GitHub Pages. Be sure to use a Quarto project (i.e., _quarto.yml) to be able to set output-dir.

.github/workflows/deploy.yml

name: Deploy

on:
  workflow_dispatch:
  push:
    branches:
      - main

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions: 
      contents: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install Quarto
        uses: quarto-dev/quarto-actions/setup@v2
        with:
          version: pre-release
      # Add any additional steps as needed, such as installing dependencies
      - name: Build
        shell: bash
        run: |
          [ ! -f _quarto.yml ] && echo -e "project:\n  output-dir: docs" > _quarto.yml
          if grep -q "output-dir: docs" _quarto.yml; then
            quarto render
          else
            quarto render --output-dir docs
          fi
      - name: Deploy
        shell: bash
        run: |
          git config --local user.name github-actions[bot]
          git config --local user.email 41898282+github-actions[bot]@users.noreply.github.com
          git add docs || echo "No changes."
          git commit -m "ci: quarto render" || echo "No changes."
          git push origin || echo "No changes."

3.2.1.2 Deploying From the Root (e.g., gh-pages Branch)

Using the root of the gh-pages branch as the source for GitHub Pages.

Tip

This method offers an advantage over quarto publish gh-pages as it does not necessitate a local run to create the gh-pages branch beforehand.
Additionally, it provides some insight into the processes that occur behind the scenes when using quarto publish gh-pages, thus when using the Quarto Publish GitHub Action.

.github/workflows/deploy.yml

name: Deploy

on:
  workflow_dispatch:
  push:
    branches:
      - main

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions: 
      contents: write
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install Quarto
        uses: quarto-dev/quarto-actions/setup@v2
        with:
          version: pre-release
      # Add any additional steps as needed, such as installing dependencies
      - name: Build
        shell: bash
        run: |
          [ ! -f _quarto.yml ] && echo -e "project:\n  output-dir: _site" > _quarto.yml
          if grep -q "output-dir: _site" _quarto.yml; then
            quarto render
          else
            quarto render --output-dir _site
          fi
      - name: Deploy
        shell: bash
        env:
          GH_PAGES: gh-pages
        run: |
          git config --local user.name github-actions[bot]
          git config --local user.email 41898282+github-actions[bot]@users.noreply.github.com
          BUILD_DIR=$(mktemp -d)
          mv _site "${BUILD_DIR}/quarto-output"
          if git ls-remote --exit-code origin "${GH_PAGES}"; then
            git fetch origin "${GH_PAGES}"
            git checkout origin/"${GH_PAGES}"
          else
            git checkout --orphan "${GH_PAGES}"
            git rm -rf .
          fi
          mv ${BUILD_DIR}/quarto-output/* .
          git add . || echo "No changes."
          git commit --allow-empty -m "ci: quarto render" || echo "No changes."
          git push origin "${GH_PAGES}" || echo "No changes."

3.2.2 GitHub Actions

For more sophisticated workflows, you have the option to customise the build process, thus eliminating the need to set up the gh-pages or docs folder. This approach is particularly advantageous as it ensures that the source repository remains uncluttered, maintaining a clear separation between the source code and the build/deploy process and environment.

.github/workflows/deploy.yml

name: Deploy

on:
  workflow_dispatch:
  push:
    branches:
      - main

permissions:
  contents: read

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: Install Quarto
        uses: quarto-dev/quarto-actions/setup@v2
        with:
          version: pre-release
      - name: Build
        shell: bash
        run: |
          [ ! -f _quarto.yml ] && echo -e "project:\n  output-dir: _site" > _quarto.yml
          if grep -q "output-dir: _site" _quarto.yml; then
            quarto render
          else
            quarto render --output-dir _site
          fi
      - name: Configure GitHub Pages
        uses: actions/configure-pages@v5
      - name: Upload Pages Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: "_site"
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4

Note

The workflow above utilises _site as the output directory, which is the default output directory for Quarto website projects. You can modify the output directory as necessary, provided it aligns with the Upload Pages Artifact step.

3.3 Keeping Your GitHub Actions Workflow Up-to-Date

GitHub Actions workflows are versioned, and new versions are released periodically. To ensure your workflows are up-to-date, you can use Dependabot to automatically create pull requests when new versions of your dependencies are available.

.github/dependabot.yml

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

This configuration file instructs Dependabot to check for updates to GitHub Actions workflows weekly.

For more information on Dependabot, see the Dependabot documentation.

4 Conclusion

By following these methods, you’ll be able to publish your Quarto projects to GitHub Pages efficiently.
Choose the approach that best suits your needs and workflow.

Happy publishing!