Publish to GitHub pages

Publish a Quarto website project to your GitHub pages using GitHub actions.

GitHub Pages

Add the GitHub Actions workflow to your project

Copy quarto-publish.yml to the folder .github/workflows/quarto-publish.yml.

on:
  push:
    branches: main
  pull_request:
    branches: main

name: Render and Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v3
        
      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Publish to GitHub Pages (and render)
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Note

If your Quarto project is not in the top level folder of your repository (in this case in /docs), then add the following path to the ‘Publish to GitHub Pages (and render)’ action:

- name: Publish to GitHub Pages (and render)
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: gh-pages
    path: docs
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Warning

Do not edit the GITHUB_TOKEN to add a personal secret to this file. This file has the same permissions as your repository, and might be publicly readable.

Run quarto publish gh-pages locally, once

Quarto needs to configure the repository for publishing through GitHub Actions. To do this, run quarto publish gh-pages locally once.

Now, add and commit the workflow file you have just created, and push the result to GitHub. This should trigger a new action from GitHub that will automatically render and publish your website through GitHub pages.

Note that GitHub Pages uses a gh-pages branch in your repository, which will be automatically created if one doesn’t exist.