Deploying to GitHub Pages

This guide sets up a GitHub Actions workflow that builds your DocAnvil docs and publishes them to GitHub Pages every time you push to main. It's the same setup these docs use.

Prerequisites

You'll need:

• A GitHub repository containing your DocAnvil project
• GitHub Pages set to deploy from GitHub Actions: go to Settings → Pages → Build and deployment → Source and choose GitHub Actions

No secrets or tokens are needed. The workflow uses GitHub's built-in Pages permissions.

Set Your Base URL

Most repositories are published as a project site at https://<user>.github.io/<repo>/. Every page lives under /<repo>/, so tell DocAnvil about it in docanvil.toml:

[build]
base_url = "/my-repo/"
site_url = "https://my-user.github.io/my-repo/"

• base_url is the path prefix for every link and asset. Without it, CSS, JS and navigation links point at the domain root and the site loads unstyled.
• site_url is the full public address. DocAnvil uses it for sitemap.xml, canonical URLs and other SEO tags.

If you publish a user or organisation site (a repository named <user>.github.io) or use a custom domain, the site is served from the root, so keep base_url = "/" and set site_url to that address.

Workflow Configuration

Create .github/workflows/docs.yml:

name: Publish docs

on:
  push:
    branches: [main]
  workflow_dispatch:

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

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Install the latest DocAnvil binary (checksum-verified)
      - name: Install DocAnvil
        run: curl -fsSL https://github.com/docanvil/docanvil/releases/latest/download/install.sh | DOCANVIL_INSTALL_DIR=/usr/local/bin sh

      - name: Build docs
        run: docanvil build --strict

      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

A few things worth noting:

• permissions grants the workflow just enough to publish: pages: write and id-token: write are what deploy-pages needs.
• concurrency makes sure only one deploy runs at a time. If you push twice in quick succession, the older run is cancelled.
• --strict fails the build on any warning, so broken wiki-links, missing images and similar problems stop the deploy before anything goes live.
• workflow_dispatch adds a Run workflow button in the Actions tab, which is handy after changing Pages settings.

Adjusting for Your Project Layout

The workflow above assumes docanvil.toml is at the root of your repository. If your docs live in a subdirectory, point the build at it and upload that folder's output:

      - name: Build docs
        run: docanvil build --strict --path docs

      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/dist

To publish only when the docs change, add a path filter to the trigger:

on:
  push:
    branches: [main]
    paths:
      - "docs/**"
      - ".github/workflows/docs.yml"

Custom Domains

Set the domain under Settings → Pages → Custom domain. Because the workflow deploys an artifact rather than a branch, you don't need a CNAME file in your output. Then update docanvil.toml so links are built for the root of your domain:

[build]
base_url = "/"
site_url = "https://docs.example.com/"

What Happens on Each Push

When you push to main:

1. GitHub Actions checks out your repository
2. The install script fetches the latest DocAnvil binary from GitHub Releases and verifies its checksum
3. docanvil build --strict builds the site into dist/, and fails if anything needs fixing
4. The output is uploaded as a Pages artifact and deployed
5. The new version is live, usually within a minute, at the URL shown on the workflow run