# Changelog

Users want to know what changed between versions, whether that's new features, bug fixes, or breaking changes. A well-maintained changelog builds trust and helps people decide when to upgrade. But keeping a separate changelog file in sync with your actual releases is tedious and error-prone.

Great Docs solves this by automatically generating a Changelog page from your GitHub Releases. Each published release becomes a section on the page, with its title, date, body content, and a link back to the release on GitHub. If you keep your release notes up to date on GitHub, your documentation site reflects them without any extra work.


# How It Works

When changelog generation is enabled (the default), `great-docs build` will:

1.  **Detect your GitHub repository**: reads the `Repository` URL from `[project.urls]` in `pyproject.toml`
2.  **Fetch releases**: calls the GitHub Releases API to retrieve published releases
3.  **Generate the page**: writes a `changelog.qmd` file in the build directory with one section per release
4.  **Add a navbar link**: adds a "Changelog" item to the site's top navigation bar

The result is a fully rendered Changelog page that stays in sync with your GitHub Releases. No manual maintenance is needed, and the page is regenerated on every build.


# Prerequisites

For changelog generation to work, Great Docs needs to know where your repository lives. Your `pyproject.toml` must include a `Repository` URL pointing to GitHub:


    pyproject.toml


``` toml
[project.urls]
Repository = "https://github.com/your-org/your-package"
```


If no GitHub URL is found, the changelog step is silently skipped and the build continues normally.


# Configuration

The changelog works out of the box with sensible defaults. You only need to add a `changelog` section to `great-docs.yml` if you want to change the behavior:


    great-docs.yml


``` yaml
changelog:
  enabled: true        # Enable/disable changelog (default: true)
  max_releases: 50     # Maximum releases to include (default: 50)
```


## Disabling the Changelog

If you don't want a changelog page at all:


    great-docs.yml


``` yaml
changelog:
  enabled: false
```


## Limiting Releases

For projects with many releases, you can cap how many appear:


    great-docs.yml


``` yaml
changelog:
  max_releases: 20
```


Releases are shown in reverse chronological order (newest first), so older releases are the ones omitted.


# Authentication

The GitHub API allows unauthenticated requests but with a low rate limit (60 requests/hour). For most projects this is sufficient because the changelog is only fetched once per build. If you hit rate limits (particularly in CI environments with many concurrent builds), set a GitHub token:


    Terminal


``` bash
export GITHUB_TOKEN=ghp_your_token_here
```


Great Docs checks for `GITHUB_TOKEN` or `GH_TOKEN` environment variables and uses whichever is set. A token raises the rate limit to 5,000 requests/hour.

> **Tip: GitHub Actions**
>
> In GitHub Actions workflows, `GITHUB_TOKEN` is already available automatically. No extra setup is needed.


# Standalone CLI Command

You can generate the changelog independently of a full build. This is useful for testing your release notes formatting or regenerating just the changelog without rebuilding the entire site:


    Terminal


``` bash
great-docs changelog
```


You can also override the max releases:


    Terminal


``` bash
great-docs changelog --max-releases 10
```


The output is written to the build directory, just as it would be during a full `great-docs build`.


# What Gets Included

Not all GitHub Releases appear on the changelog page. Here is how each release type is handled:

- **Published releases**: shown with their title, date, and body
- **Pre-releases**: included but marked with a "(Pre-release)" badge
- **Draft releases**: excluded (they aren't public yet)

The release body is rendered as Markdown, so any formatting, lists, headings, or code blocks in your GitHub Release notes carry through to the documentation site. This means the changelog page looks just as rich as your release notes on GitHub.


# Generated Output

The generated `changelog.qmd` page includes:

- A title ("Changelog") and table of contents
- An introductory line linking to the full GitHub Releases page
- One `##` section per release, containing:
  - The release name as the heading
  - A metadata line with the publication date and a "View on GitHub" link
  - The full release body as Markdown

Here's an example of what a section looks like:

``` markdown
## Version 2.0.0

*2026-01-15* · [View on GitHub](https://github.com/org/pkg/releases/tag/v2.0.0)

### What's New

- Added feature X
- Improved performance of Y

### Breaking Changes

- Removed deprecated `old_function()`
```

The page is self-contained: readers can browse all release notes in one place without leaving your documentation site.


# Edge Cases

Great Docs is designed to handle common failure scenarios gracefully. The changelog is never a hard failure; the build always completes successfully.

| Scenario | Behavior |
|----|----|
| No GitHub URL in `pyproject.toml` | Changelog step is skipped silently |
| Repository exists but has no releases | No `changelog.qmd` is created; build continues normally |
| GitHub API rate limit reached | Warning printed; partial results used if any were already fetched |
| GitHub API returns 404 | Warning printed; changelog skipped |
| Network error | Warning printed; changelog skipped |


# Next Steps

The changelog is fully automatic: Great Docs fetches your GitHub Releases, formats them into a navigable page, and regenerates it on every build. If you keep your release notes up to date on GitHub, your documentation site reflects them without any extra work.

- [Community Files](community-files.md) covers other auto-detected files like `CONTRIBUTING.md` and `ROADMAP.md`
- [Deployment](deployment.md) covers publishing your docs (including the changelog) to GitHub Pages
- [Link Checker](link-checker.md) validates that changelog links to GitHub are not broken
- [Configuration](configuration.md) covers all available `great-docs.yml` options