Changelogs

Verfasse Release Notes als gewöhnliche Inhaltsdateien oder beziehe sie aus GitHub Releases – Blume erstellt daraus automatisch eine Timeline-Seite und einen RSS-Feed.

Blume bringt ein Changelog von Haus aus mit. Schreibe jedes Release als normale Inhaltsdatei, kennzeichne es mit type: changelog, und Blume sammelt jeden Eintrag in einer generierten Übersichtsseite und einem RSS-Feed – kein Layout zu bauen, keine Liste zu pflegen. Oder verzichte ganz auf die Dateien und beziehe dein Changelog aus GitHub Releases.

Einen Eintrag schreiben

Ein Changelog-Eintrag ist eine gewöhnliche .md- oder .mdx-Seite mit type: changelog im Frontmatter. Üblicherweise liegen sie unter changelog/, aber entscheidend ist der Typ – nicht der Ordner:

---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---

A big batch of components landed this release — columns, frames, trees, and tooltips, plus code groups that render as proper language tabs.

- New `Accordion`, `Expandable`, and `Tooltip` components
- `CodeGroup` tabs with flush code blocks

Gib jedem Eintrag ein date, damit Übersicht und Feed die neuesten zuerst sortieren. Ein YAML-Datum ohne Anführungszeichen ist in Ordnung – Blume normalisiert es.

Das changelog-Objekt

Das optionale changelog-Objekt ergänzt reichhaltigere Metadaten für Übersicht und Feed:

Die Übersichtsseite

Sobald du mindestens einen Eintrag mit type: changelog hast, generiert Blume automatisch eine /changelog-Seite. Sie ist eine fokussierte Übersicht über die volle Breite – ohne Seitenleiste oder Inhaltsverzeichnis –, die jedes Release als eine Zeile auflistet, die neuesten zuerst und nach Jahr gruppiert, sodass auch eine lange Historie eine kurze Seite bleibt (deutlich unter der Größe, die ein Agent in einem einzigen Kontextfenster lesen kann):

• Der Titel des Eintrags wird zum Label der Zeile – oder v{version}, wenn kein Titel vorhanden ist. Er verlinkt auf die eigene Seite des Eintrags, wo die Release Notes vollständig gerendert werden.
• Die category wird als Tag neben dem Titel gerendert, sodass Leser auf einen Blick ein Release von einem Prerelease oder Features von Fixes unterscheiden können.
• Das Datum folgt dem konfigurierten dateFormat, ohne das Jahr, das die Gruppe der Zeile bereits anzeigt.
• Entwürfe und Einträge mit sidebar.hidden werden übersprungen.

Die Seite trägt die Überschrift Changelog (auf Englisch), darunter steht eine einzeilige Beschreibung. Lege mit changelog in deiner Konfiguration eigene fest; sie werden außerdem zum <title> der Seite, zu ihrer Meta-Description und OG-Card sowie zum Anfang ihres Markdown-Spiegels unter /changelog.md:

changelog: {
  title: "Release notes",
  description: "Every Acme SDK release, newest first.",
},

Beide akzeptieren auch eine Zuordnung von Locale-Code zu Text, wie ein Label eines Header-Tabs. Die Übersicht wird in der Standard-Locale gerendert und zeigt daher den Eintrag dieser Locale. Lässt du eines davon weg, bleibt der eingebaute Text erhalten, den ein Überschreiben der UI-Strings (changelog.title und changelog.description unter i18n.ui) ersetzt.

Die Seite erscheint nur, wenn die Route /changelog nicht bereits belegt ist.

Eine eigene Übersicht schreiben

Um etwas über der Liste zu platzieren – eine Einleitung, einen Link zum Feed, einen Hinweis zu deinem Release-Rhythmus –, schreibst du die Seite selbst und setzt <Changelog /> dort ein, wo die Liste hingehört. Die Liste verwaltet weiterhin Blume, du schreibst also nur die Teile, für die es keinen Platz vorsieht:

---
title: Changelog
description: Every Acme SDK release, newest first.
mode: center
---

Every release, newest first. Subscribe to the [RSS feed](/changelog/rss.xml) to follow along.

<Changelog />

Eine Inhaltsseite unter /changelog übernimmt die Route, sodass die generierte Seite zurücktritt und stattdessen deine gerendert wird. Lege sie unter changelog/index.mdx neben deinen Einträgen ab, damit die Changelog-Gruppe der Seitenleiste auf sie verlinkt – eine changelog.mdx neben dem Ordner fügt der Seitenleiste einen zweiten Changelog-Punkt hinzu. mode: center gibt ihr das Layout der generierten Seite – keine Seitenleiste, kein Inhaltsverzeichnis, eine breitere zentrierte Spalte –, und die generierte Seite rendert dieselbe Komponente, sodass die beiden nicht auseinanderlaufen können. Auf den Agent-Oberflächen (/changelog.md, llms-full.txt, MCP get_page, Suche) wird die Liste genauso in Markdown umgewandelt wie die der generierten Seite.

Die Liste enthält immer die Einträge der Standard-Locale, egal wo das Tag steht – nach dieser Regel richtet sich bereits jede Oberfläche, die sie veröffentlicht, sodass eine übersetzte Seite dieselben Releases auflistet, statt sich darüber zu widersprechen, welche existieren. Ihre Datumsangaben erscheinen in der Sprache der jeweiligen Seite.

Die Seite vollständig ersetzen

Für ein Design, das die Komponente nicht abbilden kann, füge unter pages/changelog.astro eine benutzerdefinierte Seite hinzu – sie übernimmt, und Blume generiert die Standard-Übersicht nicht mehr. Die <Update>-Komponente, aus der die bisherige Timeline aufgebaut war, steht weiterhin für eine von Hand verfasste Seite zur Verfügung, die Release Notes inline zeigen soll. Sie gehört nicht zu den MDX-Komponenten, importiere sie also direkt in der .astro-Seite: import Update from "blume/components/content/Update.astro";.

Wenn du die Liste selbst aufbaust, musst du nachbilden, was <Changelog /> tut – einschließlich einer Sache, die stillschweigend fehlschlägt: Einträge aus einer Quelle, die nicht das Dateisystem ist (etwa GitHub Releases), werden über eine parallele staged-Collection gerendert, sodass eine Seite, die nur getCollection("docs") liest, keinen davon auflistet – ohne Warnung. Greif lieber zu <Changelog /> in einer Inhaltsseite, es sei denn, du brauchst wirklich anderes Markup.

Aus GitHub Releases

Statt Einträge von Hand zu verfassen, richte die eingebaute githubReleases()-Quelle auf ein Repository, und jedes Release wird zu einem Eintrag mit type: changelog – dieselbe Timeline und derselbe Feed, direkt gespeist aus den Releases, die du ohnehin veröffentlichst. Blumes eigenes Changelog ist so aufgebaut:

import { filesystem, githubReleases } from "blume/sources";

content: {
  sources: [
    filesystem({ root: "content" }),
    githubReleases({
      prefix: "changelog",
      owner: "acme",
      repo: "sdk",
    }),
  ],
}

Der Name des Releases wird zum Titel, sein Tag zu changelog.version, und sein Veröffentlichungsdatum sortiert die Timeline. Jede Release-Seite erhält außerdem eine eindeutige Meta-Description, die aus ihren Notes zusammengefasst wird – Markdown entfernt, Abschnittsüberschriften und Changeset-Commit-Hash-Präfixe verworfen, gekürzt auf die Länge des Such-Snippets, die blume audit prüft – statt auf die Site-Beschreibung zurückzufallen. Ein privates Repository authentifiziert sich über die Umgebungsvariable GITHUB_TOKEN. Alle Optionen findest du unter GitHub Releases.

Einträge aus der Seitenleiste heraushalten

Changelog-Einträge sind gewöhnliche Seiten, daher listet die generierte Seitenleiste sie wie jede andere auf: Ein changelog/-Ordner oder eine githubReleases()-Quelle mit prefix: "changelog" wird zu einer Changelog-Gruppe, den neuesten Eintrag zuerst, die mit jedem Release wächst. Auch die Vorherige/Nächste-Links laufen durch sie hindurch, sodass die letzte Dokumentationsseite zum neuesten Release führen kann.

Um die Einträge aus der Seitenleiste der Dokumentation herauszuhalten, verlinke das Changelog mit einem Header-Tab statt mit einer Header-Aktion:

navigation: {
  tabs: [
    { label: "Docs", path: "/" },
    { label: "Changelog", path: "/changelog" },
  ],
}

Der Tab /changelog öffnet die Übersicht, ohne dass ein href nötig ist, und übernimmt den Abschnitt changelog/: Seiten außerhalb davon listen die Releases nicht mehr auf, und ihre Vorherige/Nächste-Links bleiben innerhalb der Dokumentation. Die eigene Seite eines Eintrags zeigt die Release-Liste als Seitenleiste. Die Übersicht, der RSS-Feed, llms.txt, die Sitemap und die Suche listen weiterhin jeden Eintrag. Der path des Tabs muss dem Ordner oder prefix entsprechen, unter dem die Einträge liegen. Der Tab Docs unter / ist optional; er gibt Lesern einen Tab, zu dem sie zurückkehren können.

Wenn du sidebar.hidden bei den Einträgen setzt, erreichst du das nicht: Damit verschwinden sie überall, auch aus der Übersicht und dem Feed.

Der RSS-Feed

Blume erstellt außerdem einen Changelog-Feed unter /changelog/rss.xml, sortiert nach date mit den neuesten zuerst. Feeds benötigen eine absolute Site-URL, setze also deployment.site; Blume fügt dann auf jeder Seite ein <link rel="alternate">-Tag ein, damit Leser den Feed automatisch entdecken.

Der Feed ist standardmäßig aktiviert. Feinjustieren kannst du ihn unter seo.rss:

seo: {
  rss: {
    enabled: true,
    types: ["blog", "changelog"],
    limit: 50,
  },
}

Entferne "changelog" aus rss.types, um den Feed wegzulassen und die Timeline beizubehalten.

Strukturierte Daten

Wenn strukturierte Daten aktiviert sind, wird jeder Changelog-Eintrag als schema.org-TechArticle mit Beschreibung und Veröffentlichungsdatum ausgegeben, sodass Suchmaschinen Releases als datierte Artikel indexieren können.