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
[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
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
changelog:
  enabled: false

Limiting Releases

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

great-docs.yml
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
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.

TipGitHub 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
great-docs changelog

You can also override the max releases:

Terminal
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:

## 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 covers other auto-detected files like CONTRIBUTING.md and ROADMAP.md
  • Deployment covers publishing your docs (including the changelog) to GitHub Pages
  • Link Checker validates that changelog links to GitHub are not broken
  • Configuration covers all available great-docs.yml options