# Set Up GitHub Pages CI

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


# Quick Setup


    Terminal


``` bash
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`:

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


## Pin the Python Version

``` yaml
- 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:

``` yaml
- 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:

``` yaml
- 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:

``` yaml
- 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:

``` yaml
- 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:

``` yaml
- 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:

``` yaml
- 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


``` bash
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.