Skip to content

Customizing changelogs

You don’t have to settle for the built-in changelog sections, there are a number of ways to customize generated changelogs. Each top-level heading on this page is a different way to customize. You can skip right to the most interesting one for you.

Before starting, here is how a version in a changelog looks by default:

## 2.0.0 (2023-10-31)
### Breaking changes
#### A breaking change
Some details about that change
### Features
#### A new feature
Some details about that feature
### Fixes
#### A bug fix
Some details about that fix
### Notes
#### A note
Some details about that note

Knope will always include these sections in the same order, but it only includes sections which contain changes.

Changing the header level

By default, the heading of a version is ##, each section is ###, and each complex change is ####. The relative level of those sections is always the same, but you can change each version to be a top-level heading (#) by modifying the last version in the changelog to be that level. Knope looks for the previous version to decide the level of the next version.

# 2.0.0 (2023-10-31)
## Breaking changes
- A breaking change
# 1.0.0
This was edited to be a top-level heading

Adding more sections

You can use the extra_changelog_sections config option to add extra sections to a changelog. This is per-package, so if you have more than one package, you’ll need to customize each changelog.

extra_changelog_sections = [
{ name = "Security", footers = ["Security"], types = ["sec"] }

You can add as many sections as you want, they will appear in order after the built-in sections. Each section can be added to from any number of conventional commit footers and changeset types. The semantic version impact of any custom changes is patch.

Overriding built-in sections

The built-in sections, as described at the top of this page, can be overridden.

Here’s some config that would override all the built-in sections, only changing their name (not their order or sources):

extra_changelog_sections = [
{ types = ["major"], name = "❗️Breaking ❗" },
{ types = ["minor"], name = "🚀 Features" },
{ types = ["patch"], name = "🐛 Fixes" },
{ footers = ["Changelog-Note"], name = "📝 Notes" },

Adding to Notes from more sources

The built-in Notes section comes from any conventional commit footers named Changelog-Note. You can override this section in the config file to add more sources:

extra_changelog_sections = [
{ name = "Notes", footers = ["Changelog-Note"], types = ["note"] }

Now, when running a CreateChangeFile step (for example, with knope document-change), the note type will be available:

? What type of change is this?
> note
[↑↓ to move, enter to select, type to filter]