Terminal
``` bash
git add .github/workflows/docs.yml
git commit -m "Add documentation workflow"
git push
```
2. **Enable GitHub Pages** in your repository:
- Go to **Settings → Pages**
- Set **Source** to `GitHub Actions`
3. **Trigger a build** by pushing to your main branch
Your documentation will be published at:
https://[username].github.io/[repository]/
# Customization Options
## Different Main Branch
Terminal
``` bash
great-docs setup-github-pages --main-branch develop
```
## Different Python Version
Terminal
``` bash
great-docs setup-github-pages --python-version 3.12
```
## Combined Options
Terminal
``` bash
great-docs setup-github-pages \
--main-branch develop \
--python-version 3.12
```
## Force Overwrite
Terminal
``` bash
great-docs setup-github-pages --force
```
# Generated Workflow
Here's what the generated workflow looks like:
.github/workflows/docs.yml
``` yaml
name: Documentation
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
build-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Set up Python
uses: actions/setup-python@v6
with:
python-version: '3.11'
- name: Set up Quarto
uses: quarto-dev/quarto-actions/setup@v2
- name: Install dependencies
run: |
pip install great-docs
pip install -e .
- name: Build documentation
run: great-docs build
- name: Upload artifact
uses: actions/upload-pages-artifact@v5
with:
path: great-docs/_site
include-hidden-files: true
publish-docs:
needs: build-docs
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v5
```
# Manual Deployment
If you prefer to deploy manually or use a different hosting service:
## Build Locally
Terminal
``` bash
great-docs build
```
## Upload the Built Site
The built site is in `great-docs/_site/`. Upload this directory to your hosting service:
- **Netlify**: Drag and drop `great-docs/_site/` folder
- **Vercel**: Point to `great-docs/_site` as output directory
- **AWS S3**: Sync the `great-docs/_site/` folder to your bucket
- **Any static host**: Copy contents of `great-docs/_site/`
# Subdirectory Deployments
If your site is hosted at a subpath rather than a domain root (for example, `https://internal.example.com/docs/mypackage/`), you need to tell Quarto the base URL so it generates correct root-relative paths for CSS, JS, and navigation links.
Set `site_url` in `great-docs.yml`:
great-docs.yml
``` yaml
site_url: "https://internal.example.com/docs/mypackage/"
```
This writes `website.site-url` into the generated `_quarto.yml` during every build, so you never have to patch the config manually.
## What it fixes
Without `site_url`, Quarto generates root-relative asset paths like `/site_libs/...` and `/reference/...`. When the site lives at a subpath, those paths resolve to the wrong location and the site appears broken (missing styles, broken navigation, 404s on the reference section, etc.).
## Versioned sites
For multi-version builds, Great Docs automatically appends the version prefix to `site-url` for non-latest versions. If your `site_url` is:
https://internal.example.com/docs/mypackage/
then version `0.2` (served at `/v/0.2/`) will use:
https://internal.example.com/docs/mypackage/v/0.2/
No extra configuration is needed.
## When you don't need it
If you deploy to a domain root (e.g., `https://yourpackage.github.io/` or a custom domain), you do not need to set `site_url`. Quarto's defaults work correctly in that case.
# Custom Domain
To use a custom domain with GitHub Pages:
1. Add a `CNAME` file to your project root (it will be copied during build):