Write release notes and changelog entries

Release notes and changelog entries serve different reading needs. A release note summarizes a named release, quarter, or other period. A changelog entry records a change identified by date, release version, or both. Both are ordinary Markdown or MDX pages with HTML and Markdown outputs and stable IDs.

Write a release note

Use type: release-note. Its title and content define the scope; neither a date nor a release version is required. This example covers a quarter without claiming one publication day:

---
id: release.q3-summary
title: Q3 2026 summary
summary: Changes grouped for the quarter.
type: release-note
slug: /releases/q3-summary
channel: production
version: current
access: { policy: public }
---

channel and version must name an enabled publication, or come from global frontmatter. A note for one release can instead use releaseVersion: "2.4" and a version in its title. releaseVersion identifies the product release; the ordinary version field selects a documentation publication. The two fields are independent. Add date only when the note has a meaningful publication date.

Write a changelog entry

Use type: changelog-entry and identify the change with date, releaseVersion, or both. The project sets which field is required. The default accepts either. A date must be a real YYYY-MM-DD calendar date; a release version must be nonempty text.

---
id: change.example
title: Example change
summary: A short description of the change.
type: changelog-entry
date: 2026-09-24
slug: /changelog/example
channel: production
version: current
access: { policy: public }
tags: [api-reference]
---

The build shows supplied dates and release versions on pages and cards, and includes them in Markdown twins. Dated changelog entries show their publication date without a separate Updated label in the page header or Markdown body. Revision dates remain in the document manifest and configured Markdown metadata. This site's Markdown metadata also projects the date and release version when present.

Set the identifier rule

Configure frontmatter.changelogIdentifier in project config:

frontmatter:
  changelogIdentifier: either

This rule does not apply to release notes. It also does not change the documentation publication's version axis.

Describe what changed

On a changelog-entry, add an optional change block to distinguish an editorial correction from a changed procedure or behavior. This fictional example describes a breaking API change:

change:
  kind: breaking
  affects: [reference.create-payment, guide.create-payment]
  migration: guide.migrate-payments

Replace these IDs with public pages in the entry's channel, version, and language. Use stable IDs without the doc: prefix. Targets resolve to their current titles and URLs. Missing, draft, self, and other-publication targets fail the build; external URLs and references to removed pages are not supported in this increment.

Choose the kind deliberately and explain scope and limitations in the entry body. behavior is not a compiler guarantee of compatibility. A missing migration link does not mean migration is unnecessary. When one release contains several distinct changes, agree on the grouping before drafting: one combined entry with clearly scoped sections, or separate entries collected in a release note. Use one change classification only when it accurately describes the combined entry; otherwise leave the entry unclassified and explain each change in its body.

change is page-specific: global defaults and enforced metadata cannot set it. It is accepted only on changelog-entry pages, not release summaries or ordinary guides. Unknown keys fail. Use the entry's existing date and releaseVersion fields for its date and release label; this block does not add an effective-date schedule or prove deployment.

HTML, full Markdown, and every published section of the entry show an Authored change notice with the kind, affected pages, and migration link when supplied. HTML links open pages; Markdown links open their twins. The corresponding documents.json record includes change.kind, resolved change.affects targets, and optional change.migration. Each target has id, title, url, and markdownUrl; URLs include the publication and base path. The entry's manifest variant supplies its publication scope.

Entries without change remain published and discoverable. Treat them as unclassified, not nonbreaking. The build checks metadata and references; it does not verify the classification or infer a breaking change from a changed digest. There is no separate semantic feed or automatic annotation of affected pages in this increment. Fetch an entry's Markdown to read its explanation.

Collect updates

For a chronological changelog, put this on an authored page:

<DocCollection type="changelog-entry" orderBy="date" />

For a version-led changelog, use orderBy="releaseVersion". Version ordering compares labels with numeric parts, so keep one consistent version scheme. Either ordered collection fails if a matching entry lacks its sort field. When entries mix dates and versions, curate the sequence with <DocCards docs={["change.one", "change.two"]} />.

Collections use the page's channel, documentation version, and language. Draft entries stay out of public builds. Stable IDs break ties. limit, exclude, and pin provide editorial control.

To roll changes into a release note, add a shared tag to entries and filter by it:

<DocCollection type="changelog-entry" tag="api-reference" orderBy="date" />

Release notes can link to entries, include a filtered collection, or stand alone. RSS feeds and blog archives remain future work.

Check the published entries

Build the site and open the note or changelog page in HTML and Markdown. Confirm its release scope, date or version, and collection links match the change you are documenting. If the page is missing, check its public access and enabled publication. Keep existing IDs and routes when revising an entry, and set updated to the edit date.

Related reading

Reference while working

• Cards and collections — Filter and order a collection of changelog entries.
• Page metadata — Look up the date and releaseVersion fields that order entries.

Related topics

• Changelog — Write dated entries and collect them with the built-in components.

Often confused with

• Use Git branches for separate docs sites — Release notes tell readers what changed; release revisions choose which Git revision of the docs to build and deploy.