# great-docs setup-github-pages


Set up automatic deployment to GitHub Pages.


``` bash
great-docs setup-github-pages [OPTIONS]
```


This command creates a GitHub Actions workflow that automatically builds and deploys your documentation when you push to the main branch.

- The workflow will:
- Build docs on every push and pull request
- Deploy to GitHub Pages on main branch pushes
- Use Quarto's official GitHub Action for reliable builds
- Install dev dependencies (auto-detected from your package manager)

The Python version is automatically detected from your pyproject.toml's `requires-python` field. Use `--python-version` to override.

- The package manager is auto-detected by checking for lock files:
- uv.lock -\> uses uv (installs dev dependencies automatically)
- poetry.lock -\> uses poetry (installs with dev dependencies)
- Otherwise -\> uses pip with optional extras like \[dev,docs\]

After running this command, commit the workflow file and enable GitHub Pages in your repository settings (Settings -\> Pages -\> Source: GitHub Actions).


<span class="gd-details-chevron" aria-hidden="true"></span>Full --help output


    Usage: great-docs setup-github-pages [OPTIONS]

      Set up automatic deployment to GitHub Pages.

      This command creates a GitHub Actions workflow that automatically builds and
      deploys your documentation when you push to the main branch.

      The workflow will:
      • Build docs on every push and pull request
      • Deploy to GitHub Pages on main branch pushes
      • Use Quarto's official GitHub Action for reliable builds
      • Install dev dependencies (auto-detected from your package manager)

      The Python version is automatically detected from your pyproject.toml's
      `requires-python` field. Use '--python-version' to override.

      The package manager is auto-detected by checking for lock files: • uv.lock
      -> uses uv (installs dev dependencies automatically) • poetry.lock -> uses
      poetry (installs with dev dependencies) • Otherwise -> uses pip with
      optional extras like [dev,docs]

      After running this command, commit the workflow file and enable GitHub Pages
      in your repository settings (Settings -> Pages -> Source: GitHub Actions).

      Examples:
        great-docs setup-github-pages                     # Auto-detect everything
        great-docs setup-github-pages --main-branch dev   # Deploy from 'dev' branch
        great-docs setup-github-pages --python-version 3.12
        great-docs setup-github-pages --package-manager uv
        great-docs setup-github-pages --force             # Overwrite existing workflow
        great-docs setup-github-pages --install-from-main # Use GitHub main branch

    Options:
      --project-path DIRECTORY        Path to your project root directory
                                      (default: current directory)
      --main-branch TEXT              Main branch name for deployment (default:
                                      main)
      --python-version TEXT           Python version for CI (default: auto-detect
                                      from pyproject.toml, or 3.11)
      --package-manager [auto|pip|uv|poetry]
                                      Package manager for installing dependencies
                                      (default: auto-detect)
      --force                         Overwrite existing workflow file without
                                      prompting
      --install-from-main             Install Great Docs from GitHub main branch
                                      instead of PyPI release
      --help                          Show this message and exit.


# Options


`--project-path: DIRECTORY`  
Path to your project root directory (default: current directory)

`--main-branch: TEXT = main`  
Main branch name for deployment (default: main)

`--python-version: TEXT`  
Python version for CI (default: auto-detect from pyproject.toml, or 3.11)

`--package-manager: CHOICE = auto`  
Package manager for installing dependencies (default: auto-detect)

`--force`  
Overwrite existing workflow file without prompting

`--install-from-main`  
Install Great Docs from GitHub main branch instead of PyPI release


# Examples

``` bash
  great-docs setup-github-pages                     # Auto-detect everything
  great-docs setup-github-pages --main-branch dev   # Deploy from 'dev' branch
  great-docs setup-github-pages --python-version 3.12
  great-docs setup-github-pages --package-manager uv
  great-docs setup-github-pages --force             # Overwrite existing workflow
  great-docs setup-github-pages --install-from-main # Use GitHub main branch
```