Create a Version Changelog

Auto-generate a changelog page from your GitHub Releases.

Great Docs can automatically generate a Changelog page from your GitHub Releases. Each published release becomes a section on the page, with its title, publication date, body content, and a link back to the release on GitHub.

Prerequisites

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 during the build.

Default Behavior

The changelog is enabled by default. If your project has a GitHub repository URL and at least one published release, great-docs build will automatically generate a changelog.qmd page and add a “Changelog” link to the navbar. No configuration is needed.

Customizing the Changelog

To change the maximum number of releases shown or to disable the changelog entirely, add a changelog section to great-docs.yml:

great-docs.yml

changelog:
  max_releases: 20    # Show only the 20 most recent releases

Releases are sorted newest-first, so older releases are the ones omitted when you set a limit.

To disable the changelog:

great-docs.yml

changelog:
  enabled: false

Write Good Release Notes

The changelog page renders the body of each GitHub Release as Markdown, so any formatting you use in your release notes carries through to the documentation. A few tips for writing release notes that render well:

Use ## headings like “What’s New”, “Bug Fixes”, and “Breaking Changes” to organize the content. Use bullet lists for individual changes. Include code snippets in fenced code blocks when showing new API usage. Keep each bullet concise but descriptive enough for users who were not involved in development.

Authentication for CI

The GitHub API allows unauthenticated requests but with a low rate limit (60 per hour). In local development this is usually fine. In CI environments, set a GITHUB_TOKEN environment variable to raise the limit:

.github/workflows/docs.yml

- name: Build docs
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: great-docs build

In GitHub Actions, GITHUB_TOKEN is already provided automatically so no extra configuration is needed.

Generate the Changelog Independently

You can generate just the changelog without running a full build using the standalone CLI command:

Terminal

great-docs changelog

This is useful for testing or for quickly regenerating the changelog after publishing a new release.

For the full reference on changelog configuration, authentication, and edge cases, see the Changelog page in the User Guide.