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, or from an explicit `id`, so a link to `#v1-2-0` points at that release.

## Syntax

```markdown
:::changelog-entry{version="1.2.0" date="2026-11-09" categories="added,fixed"}
- Add the `--verbose` flag to `mizzen 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. |
| `id` | string | the version slug | A stable id for the section and its self-link, when the generated one is not what you want. It is escaped, and repeats on one page get a numeric suffix. |
| `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

:::changelog-entry{version="1.2.0" date="2026-11-09" categories="added,fixed"}
### 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 `mizzen.yml`.
:::

:::changelog-entry{version="1.1.0" date="2026-10-02" categories="removed,security"}
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. Every entry on a page gets its own id: the first to claim one keeps it and the next get `-2`, `-3`, so repeated or slug-equivalent versions never share a fragment. The visible version and `data-version` stay exactly as authored.
- A missing or blank version shows "Unreleased" and the id `vunversioned`; a later one gets `vunversioned-2`. It never shows a bare `v`. A missing or invalid date shows "Date unknown" and no `<time>` element.
- A version with no Latin characters falls back to `vunversioned`; give it an `id` when you want a readable, stable link target.
- 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.