`granularity` is the one option the type reads. It takes `split` — the default —
or `flat`, and the difference runs further than the page count.

```ts
{
  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.path`](/reference/changelog/section)
  names the section;
- an **`llms.txt` entry** per release, so a model asking what changed in `2.1.0`
  is 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](/reference/changelog/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 shell — 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`   |

::callout{type="warning" title="A misspelled option fails the build"}
`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.
::