How to write a changelog in Markdown

To write a changelog in Markdown, list your versions newest first, give each one a version number and a release date as a heading, and group the entries under Added, Changed, Fixed, and Removed. That structure is the widely used Keep a Changelog convention. It keeps a release history that a person can read at a glance, and it's plain text, so it lives in the same repo as the code.

A changelog is for humans, not machines. A commit log records every change in the order it happened. A changelog records the changes that matter to someone using your software, in the order they'd want to read them: the latest release at the top.

The structure

Each release is its own section. The heading carries the version number and the date it shipped. Under it, you group the changes by type so a reader can scan for what they care about.

The four groups that cover almost everything:

• Added for new features.
• Changed for changes to behavior that already existed.
• Fixed for bug fixes.
• Removed for features you took out.

Two more come up often enough to know: Deprecated for features you're about to remove, and Security for anything that patches a vulnerability. Use them when you need them. Skip them when you don't.

You don't write every group in every release. A bug-fix release might have only a Fixed section. Drop the headings you don't use.

The skeleton

Here's a full changelog you can copy and start filling in. The newest release sits at the top, an Unreleased section above it collects changes that haven't shipped yet, and older releases follow in descending order.

# Changelog
 
All notable changes to this project are recorded here.
The format is based on Keep a Changelog, and this project
follows semantic versioning.
 
## [Unreleased]
 
### Added
- Drag-and-drop reordering on the queue screen.
 
## [1.2.0] - 2026-06-20
 
### Added
- Export to CSV from the reports view.
- Keyboard shortcut for "mark all read" (⌘⇧M).
 
### Changed
- The sidebar now remembers its width between launches.
 
### Fixed
- Crash when opening a file larger than 100 MB.
- Timestamps showed in UTC instead of the local timezone.
 
## [1.1.0] - 2026-05-02
 
### Added
- Dark mode.
 
### Removed
- The legacy "classic view" toggle.
 
## [1.0.0] - 2026-04-15
 
### Added
- First public release.

A few things make this readable. Each version sits in square brackets, which is the convention that lets you turn versions into links later. The date is in YYYY-MM-DD form, so it sorts and reads the same everywhere. Entries are short and start with a verb or the thing that changed, not "We added" or "This release includes."

Writing good entries

Write each line for the person affected, not the person who wrote the code. "Fixed a crash when opening files over 100 MB" tells a user something. "Patched the file handler" doesn't.

### Fixed
- Search no longer misses results that contain an apostrophe.
- Settings window opened off-screen on a second monitor.

Keep entries to one line where you can. If a change needs a paragraph, it probably needs its own release note or doc, and the changelog line should point there. One change per bullet. Past tense or plain noun phrase, consistently, not a mix.

The Unreleased section

Keep an ## [Unreleased] section at the top while you work. Every time you make a change worth recording, add a line to it. When you cut a release, you rename that section to the new version and date, and start a fresh empty Unreleased above it.

This is the part that makes a changelog stay current instead of getting reconstructed from memory the night before a release. The work is already written down.

In Unmarked

A changelog is one Markdown file, which is exactly what Unmarked is built to open and write. Keep it as CHANGELOG.md next to your project and edit it in place.

Write the entries in Write mode, where the Markdown syntax dims out of your way and reveals at the cursor. Flip to Read mode and your ### Added and ### Fixed headings render as real headings and the bullets render as lists, the way a reader sees them. The outline sidebar lists every version heading, so on a long history you can jump straight to [1.1.0] instead of scrolling.

When a release goes out, export the relevant section. PDF (⇧⌘E) gives you a clean paginated copy for release notes, and Copy as Rich Text (⌥⌘C) drops the formatted entries straight into an email or a Slack post without the raw ### and - showing.

If you link version numbers to comparison URLs (a common Keep a Changelog touch), they render as proper links and open in your browser when clicked.