Granularity
A page per release, or the file as the one page it was written as.
granularity is the one option the type reads. It takes split — the default —
or flat, and the difference runs further than the page count.
{
type: 'changelog',
path: 'CHANGELOG.md',
label: 'Changelog',
options: { granularity: 'flat' }
}
split — a page per release
The default, and what a release history is for. Each release becomes a page of its own under a generated overview, which buys four things a single page cannot have:
- a deep link to one release, and to one group inside it;
- a search hit that is the release, rather than the whole file;
- a feed item per release, once
feed.pathnames the section; - an
llms.txtentry per release, so a model asking what changed in2.1.0is handed that release and not four hundred kilobytes of history.
The overview is a timeline — every release newest first, with its date and the
kinds of change beside it, filterable by those kinds. The entries themselves stay
on the release pages: repeating them on the overview would put the whole
changelog twice into the search index, llms-full.txt and the feed.
Split pages render in a layout of their own: the releases in the sidebar, a reading column capped at a measure, and a contents column listing the groups. See Components.
flat — the file as it stands
One page, holding the file as it was written. For a project that just wants its changelog shown.
A flat changelog is an ordinary docs page and keeps the docs chrome — the prose sidebar, the breadcrumb, and a table of contents that lists the releases, which is exactly what a long file wants. That is why the layout question is answered from the declaration's own options rather than fixed by the type: the same type produces two different things.
Nothing is rewritten but the title. The file's own # Changelog goes, because
the page draws its heading from title and a second <h1> in the body is both a
duplicate and an accessibility finding. Every release heading stays exactly where
the release tool put it — which is what "unchanged" has to mean, or the mode is
not the escape hatch it exists to be.
Which to reach for
| You want | Use |
|---|---|
| A release history readers navigate and link into | split |
A feed, or per-release entries in llms.txt | split |
| The file shown as written, with no URLs invented | flat |
granularty, or a granularity that is neither of the two, stops the build with
the key or value it did not recognise. One character from the key that works is a
site quietly getting the default instead of what it configured, and the build is
the last place that can say so.