Ordner-Meta

Konfiguriere eine Sidebar-Gruppe mit einer meta.ts-Datei neben ihren Seiten — lege Titel, Icon und Reihenfolge der Gruppe sowie die Reihenfolge der darin verschachtelten Seiten fest.

Jeder Ordner in deinem Content-Baum wird zu einer Sidebar-Gruppe. Lege eine meta.ts neben die Seiten, um zu steuern, wie diese Gruppe aussieht und wie ihre Kinder sortiert werden. Das ist völlig optional: ohne eine solche Datei ist die Bezeichnung der Gruppe der lesbar aufbereitete Ordnername, und ihre Seiten werden nach Index, numerischem Präfix und dann alphabetisch sortiert.

Meta definieren

Exportiere ein defineMeta-Objekt für eine vollständig typisierte Konfiguration. Lege die Datei im Wurzelverzeichnis des Ordners ab, den sie konfiguriert — guides/meta.ts konfiguriert die Gruppe Guides:

import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  order: 2,
  collapsed: false,
  pages: ["configuration", "theming", "deployment"],
});

Jedes Feld ist optional — setze nur das, was du überschreiben möchtest.

Blume liest meta.ts-Dateien nur aus Ordnern, die dein Content abdeckt: Eine Datei in einem Ordner, den deine exclude-Globs für den Content überspringen, oder außerhalb jedes include-Globs wird nie importiert. Mit root: "." und exclude: ["src/**"] bleibt eine unabhängige src/lib/meta.ts unberührt.

Eine meta.ts außerhalb jedes include-Globs wird auch dann ignoriert, wenn ihr Ordner eine Sidebar-Gruppe ist — etwa der Tag-Ordner einer Referenz auf einer Site, deren include nur guides/** aufführt. In diesem Fall warnt Blume mit BLUME_META_OUTSIDE_INCLUDE: Füge einen include-Glob hinzu, der den Ordner erreicht, etwa "api/**/*.{md,mdx}", damit Blume sie liest.

Felder

Das pages-Array listet die Kinder nach Slug auf — dem Ordner- oder Dateinamen ohne numerisches Präfix und ohne Klammern (aus 01-quickstart.mdx wird also "quickstart"). Jedes aufgeführte Kind erhält seine Position im Array als Reihenfolge (0, 1, 2, …). Kinder, die du weglässt, erscheinen trotzdem und werden nach ihrer eigenen Reihenfolge sortiert: Eine index-Seite bleibt an erster Stelle, ein Kind mit sidebar.order, numerischem Präfix oder einem eigenen order in seiner meta.ts wird nach dieser Zahl zwischen die aufgeführten einsortiert, und ein Kind ohne all das kommt nach ihnen. Führe jedes Kind auf, wenn das Array die gesamte Reihenfolge festlegen soll. Ein Eintrag, der keine Seite und keinen Ordner der Gruppe benennt, sortiert nichts — Blume warnt deshalb mit BLUME_META_UNKNOWN_PAGE an seiner Zeile in meta.ts und schlägt den Slug vor, der am wahrscheinlichsten gemeint ist.

Das Array sortiert Seiten untereinander und Gruppen untereinander, mischt die beiden aber nicht dort, wo lose Seiten über Gruppen aufgeführt werden: auf der obersten Ebene der Sidebar (und jedes Tab-Bereichs) sowie in jeder Gruppe mit einer flat-Untergruppe, deren Überschrift sonst so wirken würde, als gehörten die nachfolgenden Seiten zu ihr. Dort listet pages: ["advanced", "intro"] die Seite intro trotzdem über der Gruppe advanced auf.

Wie Gruppen dargestellt werden — als flache Überschriften, aufklappbare Bereiche oder Drill-in-Panels — richtet sich standardmäßig nach dem sidebarweiten navigation.sidebar.display; setze hier display, um das nur für diese Gruppe zu überschreiben. Die index-Seite eines Ordners kann es zudem im Frontmatter setzen, was Vorrang vor meta.ts hat — siehe Overrides pro Gruppe.

Generierte Gruppen

Eine OpenAPI-, AsyncAPI- oder GraphQL-Referenz benennt und sortiert ihre Tag-Gruppen anhand der Spec. Um eine davon zu ändern, lege eine meta.ts in den Ordner, unter dem die Seiten des Tags veröffentlicht werden: Liegt die Referenz unter /api, konfiguriert api/pets/meta.ts in deinem Content-Ordner die Gruppe Pets. Die Felder, die sie setzt, ersetzen die generierten, und alle übrigen behalten ihre generierten Werte — eine meta.ts, die nur title setzt, behält also den Platz des Tags in der Reihenfolge der Spec.

Berechnetes Meta

Da meta.ts ein echtes Modul ist, kannst du das Meta berechnen — übergib statt eines Objekts eine Funktion (synchron oder async), um es beim Scan aufzubauen. Praktisch, um Seiten anhand einer externen Quelle zu sortieren:

import { defineMeta } from "blume";

export default defineMeta(async () => ({
  title: "Guides",
  pages: await orderFromCms(),
}));

Reihenfolge innerhalb einer Gruppe

Das pages-Array legt die Reihenfolge der Kinder einer Gruppe fest und hat Vorrang vor dem eigenen sidebar.order einer aufgeführten Seite oder dem eigenen order eines aufgeführten Unterordners. Alles, was es auslässt, fällt auf das sidebar.order im Frontmatter der jeweiligen Seite zurück und danach auf das Dateisystem (zuerst eine index-Seite, dann numerische Präfixe, dann alphabetisch). Die vollständige Sidebar-Rangfolge — einschließlich einer expliziten Sidebar-Konfiguration — findest du unter Navigation › Reihenfolge.

Um Seiten zu gruppieren, ohne ein URL-Segment hinzuzufügen, brauchst du überhaupt keine meta.ts: verwende einen geklammerten Ordnernamen — siehe Seiten › Gruppenordner.

Internationalisierung

Unter i18n wird Ordner-Meta pro Locale aufgelöst: lege eine meta.ts unter fr/guides/ ab, um die französische Gruppe unabhängig zu sortieren. Ohne eine solche Datei (oder eine gemeinsame meta.$.ts, siehe unten) übernimmt die französische Gruppe die meta.ts der Fallback-Locale.

Für Ordner-Meta, das in jeder Sprache identisch ist, füge eine $-Markierung hinzu, damit eine Datei ohne Duplizierung alle Locales bedient:

docs/guides/meta.$.ts   (folder meta applied to every locale)

Eine locale-spezifische meta.ts überschreibt die gemeinsame meta.$.ts für diese Sprache weiterhin.

Wie geht es weiter