Skip to main content
The changelog is a docs-style page for announcing what changed — releases, new features, process updates, anything your readers should know about over time. It renders as a clean timeline: date on the left, content on the right, grouped by year in the left rail.

​
How it works

The changelog is a normal doc, maintained like any other page in your docs repository — by convention it lives at changelog/index.mdx. What makes it special is its content: a series of repeating Update blocks, each with a date on the left and rich content on the right. Because it is just a doc:
  • It lives in git with full history, like everything else.
  • It opens in the same live editor as every other page — if you can edit docs, the changelog opens ready to edit, and your changes save as you type.
  • It is indexed by search, so past announcements are findable.
Each of your configured docs repositories can have its own changelog — a repo dropdown in the left rail switches between them.
There is no separate changelog database or publishing pipeline to manage. If you can edit a doc, you can maintain the changelog. Readers without edit rights see the read-only timeline.

​
Creating the changelog

If a repo has no changelog yet, the page offers a Create changelog button. It creates the page in your docs repo and opens it in the editor with a starter Update block — fill it in and it saves as you type.
If no docs repository is configured yet, the changelog page points you to Settings → Docs repositories first — the changelog needs a repo to live in.

​
Adding an entry

1

Open the changelog

Open Changelog in the navigation. With edit rights, the page is already the editor — no Edit button, no mode switch.
2

Insert an Update block

Add a new Update block at the top of the page. Set its date and write the content — headings, lists, callouts, and diagrams all work inside a block.
3

It publishes itself

Changes are committed to your docs repository automatically shortly after you stop typing — the entry is live in the timeline right away.
Changelog edits publish directly to the default branch — there is no review step in between. If an announcement needs sign-off first, draft it in a change request and merge it when approved.

​
What goes in an Update block

Each block is free-form rich content, so you can shape entries however your team likes. Common patterns:
  • Release notes — a heading per feature, with short descriptions.
  • Breaking changes — a warning callout with migration steps.
  • Process announcements — “the discount approval flow changed; see the updated guide”, with a link to the doc.
Link each entry to the docs it relates to. A changelog entry that says “the approval flow changed” is good; one that links to the updated approval-flow doc is better.

​
Agents and the changelog

Because the changelog is a normal doc, agents can maintain it too. Agents can append entries — for example, summarizing what a merged batch of doc updates changed — and those proposals go through the same review surfaces as everything else: your Inbox or a change request. Nothing is appended silently.

​
Where it appears

The changelog gets its own place in the workspace navigation, so readers can always find it. Deep links work like any other page, which makes individual announcements easy to share in Slack or email.

​
Why a doc, not a feed

Treating the changelog as a doc rather than a separate publishing system has practical benefits:
Keep the newest Update block at the top of the page. The timeline renders in document order, so entry order is entirely under your control — a misplaced block will appear exactly where you put it.