For AI agents: The complete documentation index is available at /llms.txt. A markdown version of this page is available at /layout/release-notes.md.

Release Notes

On this page

A set of components for rendering versioned changelogs with category filter chips, a sticky version selector, and deep-linkable release note items with linked issues and credits. Designed for docs sites with frequent releases.

Current version: 0.3.2 --npm

Live example

See the release notes page for a live example of how ReleaseNotes renders a versioned changelog.

Installation

$ npm install astro-better-release-notes

Import the CSS in your global stylesheet:

@import "astro-better-release-notes/style.css";

Components

ReleaseNotes

Renders the whole changelog in one call: a sticky header with the version selector and category filter chips, then every version as an <article> with its heading, date, and content.

ReleaseNotesItem

One categorized release note row, used inside each version’s MDX content. Renders a category badge that links to the row itself, the note, optional “since” and “resolved in” metadata, credits, and issue links.

ReleaseNotesSelector

The version jump dropdown. ReleaseNotes includes it automatically; use it on its own only in a custom layout.

Usage

Content collection

Each entry needs a version and a date, plus an optional release name and description:

// src/content.config.ts
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const releases = defineCollection({
  loader: glob({ pattern: '**/*.mdx', base: './src/content/releases' }),
  schema: z.object({
    version: z.string(),
    date: z.coerce.date(),
    name: z.string().optional(),
    // rendered as HTML in a collapsed summary under the version header
    description: z.string().optional(),
  }),
});

export const collections = { releases };

Each version’s MDX file uses ReleaseNotesItem for its notes:

---
version: "2.1.0"
date: 2025-05-01
name: "Dark Dolphin"
---
import { ReleaseNotesItem } from 'astro-better-release-notes';

<ReleaseNotesItem category="new-feature">Added dark mode.</ReleaseNotesItem>
<ReleaseNotesItem category="fix" issue="42" issueBaseUrl="https://github.com/org/repo/issues/">
  Fixed a login redirect loop.
</ReleaseNotesItem>

Page

Sort the entries, render each one, and pass the results to ReleaseNotes:

---
import { getCollection, render } from 'astro:content';
import { ReleaseNotes } from 'astro-better-release-notes';

const entries = (await getCollection('releases')).sort((a, b) =>
  b.data.version.localeCompare(a.data.version, undefined, { numeric: true })
);

const updates = await Promise.all(
  entries.map(async (entry) => {
    const { Content } = await render(entry);
    return { data: entry.data, Content };
  })
);
---
<ReleaseNotes {updates} />

ReleaseNotes props

PropTypeDefaultDescription
updatesReleaseEntry[]requiredRendered entries: { data: { version, date, name?, description? }, Content }
categoriesCategory[]DEFAULT_CATEGORIESCategories shown as filter chips: { id, label, color }
componentsRecord<string, any>{}Components passed to each entry’s Content, e.g. a custom ReleaseNotesItem wrapper
showSelectorbooleantrueSet false to hide the version selector

ReleaseNotesItem props

PropTypeDescription
categorystringCategory id; must match a configured category. Defaults to fix
issuestringIssue number, linked at the end of the row
bonusIssuestringSecond issue number
issueBaseUrlstringBase URL for issue links; without it, issue numbers render as plain text
thanksstringGitHub username to credit
bonusThanksstringSecond GitHub username
sincestringVersion the change applies from, linked to that version
resolvedInstringVersion a known issue was resolved in
viaIssuestringIssue that resolved a known issue
categoryColorstringBadge color; defaults to the --rn-color-{category} CSS variable
categoryLabelstringBadge label; defaults to a title-cased category id

Category filtering

The chips come from the categories prop. Checking one or more chips shows only the notes in those categories; with nothing checked, every note shows. Filtering is pure CSS, generated from your category list, so it works without JavaScript. On screens narrower than 1024px the chips sit behind a Filter button, and the button highlights while any filter is active.

To define your own categories, pass an array whose ids match the category values in your MDX:

const categories = [
  { id: 'new-feature', label: 'New Feature', color: '#16a34a' },
  { id: 'fix',         label: 'Fix',         color: '#d97706' },
  { id: 'security',    label: 'Security',    color: '#566f98' },
];

Sticky offset and scroll margins

Two CSS custom properties position the sticky header and anchored content:

  • --release-notes-top is the sticky header’s distance from the viewport top. Match it to your fixed nav height. Default: 3.5rem.
  • --release-notes-scroll-margin is the scroll-margin-top on version headings and note rows, which are the anchor targets. Set it to at least the distance from the viewport top to the bottom edge of the release notes sticky header, or anchored headings land underneath it. The chip rows wrap with viewport width, so measure at each breakpoint. Default: 5rem.
:root {
  --release-notes-top: 3.25rem;
  --release-notes-scroll-margin: 7.5rem;
}
@media (min-width: 1024px) {
  :root { --release-notes-scroll-margin: 15rem; }
}

Theming

Set these on :root and .dark to match your palette. Dark mode uses a .dark ancestor class.

VariableLight defaultDark defaultUsed for
--rn-bgwhite#0f172aSticky header background
--rn-border#d1d5db#4b5563Selector and Filter button borders
--rn-input-bg#f3f4f6#1e293bSelector and Filter button background
--rn-text#111827#cbd5e1Selector text
--rn-text-muted#374151#cbd5e1Filter button text
--rn-focus#6366f1#818cf8Focus rings and the active-filter indicator
--rn-chip-bg#f1f5f9#1e293bUnselected chip background
--rn-chip-border#cbd5e1#475569Unselected chip border
--rn-chip-color#334155#cbd5e1Unselected chip text
--rn-summary-border12% of the text colorsameSummary box border and divider
--rn-summary-bg6% of the text colorsameSummary bar background
--rn-summary-hover-bg10% of the text colorsameSummary bar background on hover
--rn-color-{category}see DEFAULT_CATEGORIESsameCategory color for chips and badges
--release-notes-link-color#4338ca—Issue link and version permalink color
--release-notes-link-color-dark—#818cf8Issue link and version permalink color in dark mode
--release-notes-link-hover-color#9a3412—Link, permalink, and badge hover color
--release-notes-link-hover-color-dark—#fed7aaLink, permalink, and badge hover color in dark mode
--release-notes-anchor-size1.5emsameVersion permalink size; match it to your h2 size

When you map these to your own palette, keep --rn-chip-color and --rn-text-muted at a 4.5:1 contrast ratio or better against --rn-chip-bg and --rn-input-bg.

Accessibility

  • Each version is an <article> labelled by its <h2>, and the <h2> carries the anchor id (version-2-1-0). Fragment links, search crawlers, and TOC tools all resolve to the heading. The # permalink sits next to the heading, so the heading’s accessible name is only the version.
  • Category filters are native checkboxes in a <fieldset> with a visually hidden <legend>. They work with Tab and Space, show a focus ring on the chip, and announce their checked state. Selected chips also show a check mark, so state doesn’t rely on color.
  • Badge and selected-chip text is mixed from the category color (darker in light mode, lighter in dark mode), which keeps the default categories at 4.5:1 or better.
  • The version selector is labelled, and its options are bare version numbers, so typing 1.56 jumps to 1.56.0. Each jump is announced through a polite live region. Focus stays on the selector so type-ahead and arrow keys keep working: it scrolls with scrollIntoView and updates the URL with history.replaceState, because assigning location.hash would blur it. Jumps don’t add browser history entries.
  • Each version’s summary is a native <details>. It opens with Enter or Space and announces its state without JavaScript, and its text stays in the HTML for search, find-in-page, and LLM tools. A visually hidden version number gives each summary a unique accessible name, such as “Summary of version 2.1.0”.
  • Transitions, the summary chevron rotation, and the badge hover scale are turned off under prefers-reduced-motion: reduce.

Upgrading to 0.3.2

  • The version summary is now a bordered box with a tinted bar and a chevron, styled like a details component, instead of a plain disclosure triangle. Its colors mix from the surrounding text color, so it follows light and dark mode. Override them with --rn-summary-border, --rn-summary-bg, and --rn-summary-hover-bg.
  • Each summary’s accessible name now includes its version.

Upgrading to 0.3.1

  • description now renders as HTML, so it can contain inline markup such as links. Escape a literal < or & in a plain-text description.

Upgrading to 0.3.0

  • An entry with a description now shows it in a collapsed <details> summary under the version header. Entries without one render as before.

Upgrading to 0.2.3

  • Version selector options no longer start with “Version” (1.56.0 (SSO Snake) instead of Version 1.56.0 (SSO Snake)).
  • Choosing a version updates the URL with history.replaceState instead of adding a history entry, so the Back button leaves the page rather than stepping back through jumps.
  • The version permalink now uses the link color variables and --release-notes-anchor-size instead of inheriting the surrounding text color and size.

Upgrading to 0.2.2

Anchor URLs are unchanged, but the markup moved:

  • The version id moved from <article class="version"> to its <h2>. Update CSS or scripts that target article.version[id] or .version:target.
  • --release-notes-scroll-margin now applies to the heading, which sits below the top of the article. If anchored headings land under your sticky header, increase the value.
  • The permalink is .version-title .anchor-link, outside the <h2>. Update selectors that used .release-note .anchor-link.
  • The filter container is a <fieldset> instead of a <nav>, and keeps its release-notes-filters id and filter-controls class.