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.
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
| Prop | Type | Default | Description |
|---|---|---|---|
updates | ReleaseEntry[] | required | Rendered entries: { data: { version, date, name?, description? }, Content } |
categories | Category[] | DEFAULT_CATEGORIES | Categories shown as filter chips: { id, label, color } |
components | Record<string, any> | {} | Components passed to each entry’s Content, e.g. a custom ReleaseNotesItem wrapper |
showSelector | boolean | true | Set false to hide the version selector |
ReleaseNotesItem props
| Prop | Type | Description |
|---|---|---|
category | string | Category id; must match a configured category. Defaults to fix |
issue | string | Issue number, linked at the end of the row |
bonusIssue | string | Second issue number |
issueBaseUrl | string | Base URL for issue links; without it, issue numbers render as plain text |
thanks | string | GitHub username to credit |
bonusThanks | string | Second GitHub username |
since | string | Version the change applies from, linked to that version |
resolvedIn | string | Version a known issue was resolved in |
viaIssue | string | Issue that resolved a known issue |
categoryColor | string | Badge color; defaults to the --rn-color-{category} CSS variable |
categoryLabel | string | Badge 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-topis the sticky header’s distance from the viewport top. Match it to your fixed nav height. Default:3.5rem.--release-notes-scroll-marginis thescroll-margin-topon 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.
| Variable | Light default | Dark default | Used for |
|---|---|---|---|
--rn-bg | white | #0f172a | Sticky header background |
--rn-border | #d1d5db | #4b5563 | Selector and Filter button borders |
--rn-input-bg | #f3f4f6 | #1e293b | Selector and Filter button background |
--rn-text | #111827 | #cbd5e1 | Selector text |
--rn-text-muted | #374151 | #cbd5e1 | Filter button text |
--rn-focus | #6366f1 | #818cf8 | Focus rings and the active-filter indicator |
--rn-chip-bg | #f1f5f9 | #1e293b | Unselected chip background |
--rn-chip-border | #cbd5e1 | #475569 | Unselected chip border |
--rn-chip-color | #334155 | #cbd5e1 | Unselected chip text |
--rn-summary-border | 12% of the text color | same | Summary box border and divider |
--rn-summary-bg | 6% of the text color | same | Summary bar background |
--rn-summary-hover-bg | 10% of the text color | same | Summary bar background on hover |
--rn-color-{category} | see DEFAULT_CATEGORIES | same | Category color for chips and badges |
--release-notes-link-color | #4338ca | — | Issue link and version permalink color |
--release-notes-link-color-dark | — | #818cf8 | Issue 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 | — | #fed7aa | Link, permalink, and badge hover color in dark mode |
--release-notes-anchor-size | 1.5em | same | Version 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.56jumps 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 withscrollIntoViewand updates the URL withhistory.replaceState, because assigninglocation.hashwould 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
descriptionnow 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
descriptionnow 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 ofVersion 1.56.0 (SSO Snake)). - Choosing a version updates the URL with
history.replaceStateinstead 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-sizeinstead 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 targetarticle.version[id]or.version:target. --release-notes-scroll-marginnow 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 itsrelease-notes-filtersid andfilter-controlsclass.