Create a dated Markdown changelog with comparison links
Admin ·
Build a Markdown file that separates upcoming work from released changes. Give each release a date, place user-facing notes in the relevant categories and add a comparison address when readers need a way to inspect the changes.
Check the order of two dated versions
Select Load example. Changelog Markdown opens with Unreleased. It then lists version 1.4.0 dated 2026-11-20 before version 1.3.0 dated 2026-10-29, even though 1.3.0 was entered first.
The three visible change sections are Added for Unreleased, Fixed for 1.4.0 and Added for 1.3.0. Turn on Keep empty headings to include all six category headings in each section, then turn it off to return to the filled headings.
# Changelog
## [Unreleased]
## [1.4.0] - 2026-11-20
## 1.3.0 - 2026-10-29Add a security note and check the comparison destinations
Set Section to edit to Release 2 · 1.4.0 and Change category to Security. Enter Validate imported map formats. The note appears under Security in 1.4.0. The existing Fixed note stays in its category.
Read the reference definitions at the bottom of the Markdown. The 1.4.0 comparison goes from v1.3.0 to v1.4.0. Unreleased compares v1.4.0 to HEAD. This example uses illustrative addresses on example.com. Supply the actual comparison addresses for your project.
Keep a Changelog 1.1.0CommonMark 0.31.2 reference link definitions
Open the saved changelog and verify the headings
Download CHANGELOG.md and open it in your Markdown reader. Confirm that Unreleased and 1.4.0 render as linked headings and that 1.3.0 remains plain text. Review each destination against the compared tags before publishing the file.
When you add another release, use a date such as 2026-11-20 and a version such as 1.4.1. Correct an invalid calendar date or duplicate version label before exporting. Enter one change per line for each category you need.
Keep a Changelog 1.1.0CommonMark 0.31.2 reference link definitionsSemantic Versioning 2.0.0
Common questions
What should I put in Unreleased?
Record noteworthy changes waiting for a release. Move them into a dated version when you publish it.
Can I start with a prerelease version?
Yes. Enter a valid semantic version such as 1.5.0-rc.1 and give it its own release date.