# Create a Version Changelog

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


``` 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


``` yaml
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


``` yaml
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


``` yaml
- 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


``` bash
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](../user-guide/changelog.md) page in the User Guide.