Deploy to GitHub Pages

Set up automatic deployment with GitHub Actions

Deploy to GitHub Pages

This guide shows how to automatically deploy your documentation to GitHub Pages.

Generate GitHub Actions Workflow

QuartoDocBuilder can generate a GitHub Actions workflow for you:

using QuartoDocBuilder
quarto_github_action()

This creates .github/workflows/docs.yml.

You can override the defaults:

quarto_github_action(
    quarto_version = "pre-release",       # Quarto version (pre-release has Julia support)
    julia_version = "1",                  # Julia version
    output_dir = "site",                  # Quarto output directory
    trigger_branches = ["main", "master"] # branches that trigger the build
)

Workflow Contents

The generated workflow:

1. Triggers on pushes (and PRs) to the configured branches
2. Installs Julia and Quarto, caching Julia packages
3. Runs julia --project=docs docs/make.jl to build the Quarto project
4. Runs quarto render
5. Uploads docs/site and deploys it to GitHub Pages (on main/master)

name: Build and Deploy Documentation

on:
  push:
    branches: ["main", "master"]
  pull_request:
    branches: ["main", "master"]
  workflow_dispatch:

permissions:
  contents: write
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: julia-actions/setup-julia@v2
        with:
          version: '1'
      - name: Install Julia dependencies
        run: |
          julia --project=docs -e '
            using Pkg
            Pkg.develop(PackageSpec(path=pwd()))
            Pkg.instantiate()
          '
      - name: Build documentation (Julia)
        run: julia --project=docs docs/make.jl
      - uses: quarto-dev/quarto-actions/setup@v2
        with:
          version: pre-release
      - name: Render Quarto site
        run: cd docs && quarto render
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/site

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master'
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

Enable GitHub Pages

1. Go to your repository Settings
2. Click Pages in the sidebar
3. Under “Build and deployment”, select GitHub Actions
4. Push to main to trigger the first build

Custom Domain

To use a custom domain:

1. Add a CNAME file to docs/ with your domain
2. Configure DNS records for your domain
3. Enable HTTPS in GitHub Pages settings

Troubleshooting

Build Fails

Check the Actions log for errors. Common issues:

• Missing dependencies in docs/Project.toml
• Quarto rendering errors
• Julia compilation errors

Pages Not Updating

• Ensure the workflow completed successfully
• Check that docs/site/ is being uploaded
• Wait a few minutes for GitHub to deploy

404 Errors

• Verify output_dir = "site" in your config
• Check that _quarto.yml is generated correctly