Set Up GitHub Pages CI

Automate documentation builds and deployment with GitHub Actions.

Great Docs includes a one-command setup for continuous deployment to GitHub Pages.

Quick Setup

Terminal

great-docs setup-github-pages

This generates a GitHub Actions workflow at .github/workflows/docs.yml that:

1. Checks out your repository
2. Installs Python and your package
3. Runs great-docs build
4. Deploys the _site/ output to GitHub Pages

Enable GitHub Pages in Your Repo

After pushing the workflow:

1. Go to Settings → Pages in your GitHub repository
2. Under Source, select GitHub Actions
3. Push a commit to the configured branch (default: main)

The workflow runs automatically on every push to the target branch.

Customizing the Workflow

The generated workflow uses sensible defaults. Common customizations:

Change the Trigger Branch

Edit .github/workflows/docs.yml:

on:
  push:
    branches: [develop]  # Build on develop instead of main

Pin the Python Version

- uses: actions/setup-python@v6
  with:
    python-version: "3.12"  # Pin to a specific version

Full Git History for Page Timestamps

Great Docs displays “Created” and “Last updated” timestamps on documentation pages using Git history. The generated workflow already includes fetch-depth: 0 to enable this:

- uses: actions/checkout@v6
  with:
    fetch-depth: 0  # Full history for accurate page timestamps

Without full history (the default shallow clone), all pages would show identical timestamps. If you have a very large repository and want faster builds, you can use sparse checkout to fetch full history only for documentation files:

- uses: actions/checkout@v6
  with:
    fetch-depth: 0
    sparse-checkout: |
      user_guide
      recipes
      README.md
      ROADMAP.md

Add a Changelog Token

The changelog feature needs API access to fetch releases. In GitHub Actions, GITHUB_TOKEN is available automatically:

- name: Build docs
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: great-docs build

The generated workflow already includes this (no extra setup needed).

Package Manager Detection

Great Docs automatically detects your project’s package manager and generates the appropriate install commands:

Lock File	Package Manager	Install Command
uv.lock	uv	uv sync (includes dev dependencies)
poetry.lock	poetry	poetry install (includes dev dependencies)
Neither	pip	pip install -e . with optional extras

uv Projects

If your project uses uv, the workflow installs all dependencies from your lock file:

- name: Install package and dependencies
  run: |
    python -m pip install uv
    uv sync
    uv pip install git+https://github.com/posit-dev/great-docs.git

Poetry Projects

For poetry projects:

- name: Install package and dependencies
  run: |
    python -m pip install poetry
    poetry install
    poetry run pip install git+https://github.com/posit-dev/great-docs.git

pip Projects with Optional Dependencies

For pip-based projects, Great Docs scans your pyproject.toml for optional dependency groups like dev, docs, test, or notebook and includes them automatically:

- name: Install package and dependencies
  run: |
    python -m pip install --upgrade pip
    python -m pip install -e ".[dev,docs]"
    python -m pip install git+https://github.com/posit-dev/great-docs.git

This ensures that dependencies needed for documentation notebooks (like visualization libraries) are installed in CI.

Override Package Manager Detection

Use the --package-manager flag to override auto-detection:

Terminal

great-docs setup-github-pages --package-manager pip  # Force pip even if uv.lock exists
great-docs setup-github-pages --package-manager uv   # Force uv

Verifying the Deploy

After the first successful run, your docs are live at:

https://<username>.github.io/<repo>/

Check the Actions tab in your repo to see build logs and troubleshoot any issues.