Release notes
Write one Markdown file per release and get a changelog page, a page per release and the portal releases table.
A section of kind changelog reads changelog/<locale>/ in the project folder, one Markdown file per release.
JSONproject.json
{
"nav": {
"sections": [
{ "id": "guides", "label": "Guides", "kind": "guides" },
{ "id": "changelog", "label": "Changelog", "kind": "changelog" }
]
}
}mdchangelog/en/2.4.0.md
---
version: 2.4.0
date: 2026-10-02
title: Scheduled jobs and webhook retries
status: features
---
- Jobs can run on a cron schedule. See [scheduled jobs](../../docs/2.4/en/guides/scheduled-jobs.md).
- Webhook deliveries are retried with backoff.| Field | Required | Value |
|---|---|---|
version |
yes | Release version. Also the URL slug: /<project>/changelog/2.4.0/. |
date |
yes | YYYY-MM-DD. Releases are sorted by date, newest first. |
title |
yes | One line on what changed. |
status |
no | features (default), stable, breaking, beta or deprecated. Sets the badge. |
The section shows a list of every release and one page per release. The portal home lists the five latest releases
of all projects, unless home.showReleases is false in site.json.
Write links to Markdown files and images relative to the release file, as in the example above. A link to a docs page
opens that page in the current version: here /<project>/guides/scheduled-jobs/.
A release missing in a locale is shown from the fallback locale.