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.

Caution

Knope expects versions in the changelog to look similar to how it would generate them, specifically it must start with a valid semantic version. If you have a different format for your pre-existing headers, you’ll need to update the latest version to Knope’s format.

# 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.

knope.toml

[package]
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.

Caution

The default order is recommended, as it organizes changes from most-important (for consumers) to least-important. Overridden sections always appear after non-overridden sections in the order they’re defined. So, if you’re going to override any of the first three sections, it’s recommended you also override any sections that should appear below them.

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

knope.toml

[package]
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:

knope.toml

[package]
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?
  major
  minor
  patch
> note
[↑↓ to move, enter to select, type to filter]