Changelog entry

2 minutes read

A changelog entry is one release: a version heading that links to itself, the release date, the categories the release touches, and the entry text. The heading and section id come from the version, so a link to #v1-2-0 points at that release.

Syntax

:::changelog-entry{version="1.2.0" date="2026-11-09" categories="added,fixed"}
- Add the `--verbose` flag to `slipway build`.
- Fix a crash when `site.config.md` is missing.
:::

Options

Name Type Default What it does
version string Unreleased The release version, such as 1.2.0 or v1.2.0. It becomes the id v1-2-0 and the link target.
date string Date unknown An ISO date, YYYY-MM-DD; a date-time keeps its date part. A real date renders a <time datetime>.
categories string none Comma-separated names, or a JSON array: added, changed, fixed, removed, security. Unknown names are dropped and repeats are removed.

Example

1.2.0

Faster builds

The engine caches the Markdown stage, so a second build skips pages whose source did not change.

Fixed

A missing site.config.md no longer stops a build that takes its config from slipway.yml.

1.1.0

The old theme's blocks folder is gone. Every block has a component page under components or a Markdown equivalent.

Notes

  • The section id is v plus a slug of the version: lower case, dots to dashes, other runs of characters to one dash. A leading v is not doubled. Two entries on one page need different versions, or they share an id.
  • A missing or blank version shows "Unreleased" and the id vunversioned; it never shows a bare v. A missing or invalid date shows "Date unknown" and no <time> element.
  • An empty body keeps the heading, date, and categories, and adds a short "No details for this release" paragraph, so a stub is visibly a stub.
  • Each category is an icon and a text label. The icon and label carry the meaning, so the difference between categories does not depend on color.
  • Dates use the page's calendar: English shows Gregorian, Persian Jalali, and Arabic Hijri.
View Markdown

Use with an agent
View Markdown

Open in