Navigation

Blume erstellt die Seitenleiste aus deinen Dateien und lässt dich sie dann per Frontmatter, Ordner-Meta oder Konfiguration verfeinern – Breadcrumbs und Gliederungen folgen automatisch.

Blume erstellt deine Seitenleiste aus dem Dateisystem und lässt dich sie dann so weit verfeinern, wie du möchtest – Seite für Seite, Ordner für Ordner oder mit einer einzigen expliziten Konfiguration. Breadcrumbs, Zurück-/Weiter-Links und die Gliederung auf der Seite ergeben sich alle aus demselben Modell, ganz ohne Verkabelung.

Standardmäßig spiegelt die Seitenleiste deinen Inhaltsbaum wider:

Ordner werden zu Gruppen, Dateien werden zu Seiten
Die Beschriftung einer Seite ist ihr Frontmatter-title; die Beschriftung einer Gruppe ist der lesbar gemachte Ordnername
Einträge werden nach numerischem Präfix sortiert, dann alphabetisch, und die index-Seite eines Ordners steht an erster Stelle
Ein Ordner mit einer index-Seite verlinkt seine Gruppenzeile auf diese Seite, sodass ein Klick auf den Abschnittsnamen die Landing-Page des Abschnitts öffnet

Für viele Websites reicht das bereits – alles Weitere ist optional.

Seitenbeschriftung, Symbol und Badge

Passe im Frontmatter unter sidebar an, wie eine einzelne Seite in der Seitenleiste erscheint:

sidebar:
  label: Quickstart # override the title in the sidebar
  icon: rocket # an icon from Blume's built-in set
  badge: New # a small label beside the entry
  order: 1 # sort position within its group

Das vollständige Seitenschema findest du unter Frontmatter.

Ordnergruppen

Jeder Ordner wird zu einer Gruppe in der Seitenleiste. Lege eine meta.ts neben die Seiten, um Titel, Symbol und Reihenfolge der Gruppe sowie die Reihenfolge ihrer untergeordneten Einträge festzulegen:

import { defineMeta } from "blume";

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

Unter Ordner-Meta findest du alle Felder sowie Informationen zur Berechnung von Meta-Daten während des Scans.

Das meta.title eines Ordners und das Frontmatter-title seiner eigenen index-Seite werden unabhängig voneinander aufgelöst – übersetzt du unter i18n das eine und vergisst das andere, entsteht eine korrekte Seitenleiste mit einem veralteten <title> bzw. einer veralteten Überschrift auf der Landing-Page selbst. Blume meldet eine BLUME_NAV_INDEX_TITLE_MISMATCH-Warnung, wenn beide voneinander abweichen. Nicht übersetzte Seiten, die aus der Fallback-Sprache ergänzt werden, sind davon ausgenommen – ihr Titel gehört zur Fallback-Sprache, und die Lösung besteht darin, die Seite zu übersetzen, nicht ihr Frontmatter zu bearbeiten.

Um Seiten zu gruppieren, ohne ein URL-Segment hinzuzufügen, verwende einen in Klammern gesetzten Ordnernamen – siehe Seiten.

Anzeigemodi

navigation.sidebar.display legt fest, wie jede Gruppe in der Seitenleiste dargestellt wird:

navigation: {
  sidebar: {
    display: "flat", // "flat" | "group" | "page"
  },
}

flat (Standard) – eine nicht einklappbare Überschrift mit den darunter aufgelisteten Seiten. Seiten, die zu keiner Gruppe gehören, stehen immer zuerst, oberhalb der Gruppenabschnitte, damit sie nicht für untergeordnete Einträge einer Gruppe gehalten werden.
group – ein einklappbares <details>-Element pro Gruppe. Gruppen sind standardmäßig zunächst eingeklappt; eine Gruppe, welche die aktuelle Seite enthält, ist immer aufgeklappt, sodass nur der Abschnitt geöffnet ist, in dem du dich befindest. Setze collapsed: false im Ordner-Meta, um eine Gruppe unabhängig davon offen zu erzwingen.
page – jede Gruppe ist eine einzelne Zeile, die beim Anklicken die Seitenleiste in ein Unterpanel schiebt, das nur die Einträge dieser Gruppe zeigt, mit einem Zurück-Pfeil oben. Das Panel ist routen-bewusst, sodass beim direkten Aufruf einer Seite innerhalb der Gruppe sofort dorthin geöffnet wird.

Sowohl im group- als auch im page-Modus wird ein Abschnitt, der auf der aktuellen Seite nicht geöffnet ist, aus dem HTML dieser Seite weggelassen und beim ersten Öffnen nachgeladen (er wird bereits vorab geladen, sobald Zeiger oder Fokus seine Zeile erreichen, sodass das Öffnen meist sofort erfolgt, und ein einmal geladener Abschnitt bleibt für den Rest des Besuchs erhalten). Auf einer großen Website macht das den Großteil des Gewichts einer Seite aus: Nur die Zeilen des geöffneten Abschnitts werden mit der Seite ausgeliefert. Die Zeilen sind vorgerenderte Fragmente unter /blume-nav/, daher brauchen sie keinen Server. Lesende ohne JavaScript sehen den geöffneten Abschnitt und die Gruppenzeilen; die Sitemap, die Zurück-/Weiter-Links und der geöffnete Abschnitt halten jede Seite für Crawler erreichbar.

Überschreibungen pro Gruppe

Jede generierte Gruppe kann sich vom globalen Modus abmelden – ganz ohne explizite Seitenleiste. Setze display in der meta.ts des Ordners oder – wenn der Ordner eine index-Seite hat – unter sidebar im Frontmatter dieser Seite, und nur diese eine Gruppe ändert sich:

import { defineMeta } from "blume";

export default defineMeta({
  title: "Client SDKs",
  display: "page",
});

---
title: Client SDKs
sidebar:
  display: page
---

Der effektive Modus einer generierten Gruppe wird nach absteigender Priorität aufgelöst:

sidebar.display im Frontmatter der eigenen index-Seite der Gruppe
display in der meta.ts des Ordners
Das globale navigation.sidebar.display
Der Blume-Standard (flat)

Das display einer Gruppe gilt nur für diese Gruppe – verschachtelte Untergruppen lösen ihren eigenen Wert über dieselbe Kette auf. Eine Gruppe im page-Modus mit einer Index-Seite navigiert weiterhin in ihr Unterpanel: Die Index-Seite wird als erster Eintrag des Panels aufgeführt, und beim Aufruf ihrer URL öffnet sich das Panel direkt.

sidebar.display bedeutet an allen anderen Stellen nichts – auf einer Nicht-Index-Seite, auf der eigenen index-Seite des Inhalts-Roots (der Root ist keine Gruppe; verwende navigation.sidebar.display) oder auf jeder Seite, wenn eine explizite Seitenleiste konfiguriert ist (deren Einträge bestimmen den Modus jeder Gruppe) –, daher meldet Blume eine BLUME_SIDEBAR_DISPLAY_IGNORED-Warnung, statt es stillschweigend zu verwerfen. collapsed bleibt spezifisch für den group-Modus; es ist wirkungslos, wenn eine Gruppe zu flat oder page aufgelöst wird.

Eine Gruppe in einer expliziten Seitenleiste überschreibt den globalen Modus mit einem eigenen display, genau wie zuvor.

Reihenfolge

Wenn die Seitenleiste generiert wird, wird die Reihenfolge nach absteigender Priorität aufgelöst:

Konfigurierte Seitenleiste

Eine explizite navigation.sidebar ersetzt den generierten Baum vollständig.

Ordner-Meta

Das pages-Array in meta.ts bestimmt die Reihenfolge einer Gruppe.

Frontmatter

sidebar.order auf einer Seite.

Dateisystem

Zuerst eine index-Seite, dann numerische Präfixe, dann alphabetisch nach Beschriftung.

Zwei gleichrangige Einträge mit derselben expliziten oder numerischen Reihenfolge werden untereinander alphabetisch sortiert – Blume meldet eine BLUME_DUPLICATE_SIDEBAR_ORDER-Warnung, damit der Gleichstand nicht unbemerkt bleibt.

Ausgeblendete Seiten

Blende eine Seite aus der Seitenleiste – und aus der Zurück-/Weiter-Navigation – aus, während sie weiterhin gebaut und über ihre URL erreichbar bleibt:

sidebar:
  hidden: true

Die index-Seite eines Ordners erscheint sowohl als Link der Gruppenzeile als auch als erste Zeile innerhalb der Gruppe. Blende die Index-Seite aus, um nur die verlinkte Überschrift zu behalten: Die Gruppenzeile öffnet weiterhin die Landing-Page, und die Zurück-/Weiter-Links führen weiterhin durch sie hindurch.

Tabs

Stelle Abschnitte der obersten Ebene als Tabs im Header dar – nützlich, um eine große Website in eigenständige Bereiche zu unterteilen, etwa Adapter, eine API und KI-Leitfäden. Ein Tab wird hervorgehoben, wenn die aktuelle Route unter seinen path fällt:

navigation: {
  tabs: [
    { label: "Adapters", path: "/adapters", icon: "plug" },
    { label: "API", path: "/api", icon: "rocket" },
    { label: "AI", path: "/ai", icon: "sparkles" },
  ],
}

Eine aktivierte OpenAPI- oder AsyncAPI-Referenz wird unter ihrer Route eingebunden, fügt aber nicht von sich aus einen Tab hinzu – richte einen Tab auf diese Route, um sie im Header sichtbar zu machen (und, beim nativen Renderer, um ihre Operations-Seitenleiste einzugrenzen), mit einer Beschriftung deiner Wahl:

navigation: {
  tabs: [
    { label: "API", path: "/reference" },
  ],
}

Der path eines Tabs ist sein Abschnittspräfix und dient zugleich als Linkziel. Ein Abschnitt, dessen path keine eigene Seite ist – ein Ordner ohne index.mdx –, würde auf einen 404 verweisen, daher greift der Tab stattdessen auf die erste Seite im Abschnitt zurück. Setze href, wenn er woanders landen soll:

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

Das ist wichtig für Routen, die nicht Teil des Inhaltsbaums sind, da der Fallback sie nicht sehen kann: der generierte Changelog-Index oder eine benutzerdefinierte Seite, die du unter pages/ hinzugefügt hast. Ohne href landet ein /changelog-Tab auf dem neuesten Eintrag statt auf dem Index. Tabs, die kein href setzen, sind nicht betroffen.

Auf einer i18n-Website kann die label eines Tabs (und die eines Dropdown-Eintrags) statt einer Zeichenkette eine Zuordnung pro Sprache sein – der Eintrag der aktiven Sprache gewinnt, danach der der Standardsprache:

navigation: {
  tabs: [
    { label: { en: "Docs", fr: "Documentation" }, path: "/docs" },
    { label: "CLI", path: "/cli" }, // a plain string renders as-is everywhere
  ],
}

Tabs grenzen außerdem die Seitenleiste ein: Wenn die aktuelle Route unter den path eines Tabs fällt, zeigt die Seitenleiste nur die Seiten dieses Abschnitts – /adapters/* listet also die Adapter und sonst nichts. Der Ordner am path eines Tabs wird zum Abschnitt, sodass dafür über die Tabs hinaus keine zusätzliche Konfiguration nötig ist; strukturiere deine Inhalte in einen Ordner pro Tab und richte jeden Tab darauf aus.

Auf einer Route, die unter keinem Tab liegt (oder unter einem Tab, dessen path / ist), zeigt die Seitenleiste die Seiten, die nicht zu einem Tab gehören – der Ordner jedes Tabs wird darin ausgeblendet, da dieser Abschnitt bereits einen eigenen Tab im Header hat. Eine Root-Landing-Page listet also deine losen Seiten der obersten Ebene, während die in Abschnitte gegliederten Inhalte hinter ihrem Tab bleiben – analog zu den Root-Ordnern von Fumadocs. Hat eine Route auf diese Weise keine eigenen Seiten anzuzeigen, wird stattdessen der vollständige Baum gezeigt, damit die Seitenleiste nie leer bleibt.

Selektoren

Zum Wechseln zwischen ganzen Partitionen einer Website – einem Produkt, einer Version oder einer beliebigen gruppierten Menge von Zielen – füge einen selector hinzu. Jeder wird als Dropdown im Header dargestellt und zeigt die Option, deren path zur aktuellen Route passt:

navigation: {
  selectors: [
    {
      kind: "version",
      label: "Version",
      items: [
        { label: "v2 (latest)", path: "/v2", icon: "rocket" },
        { label: "v1", path: "/v1" },
      ],
    },
  ],
}

Jeder Eintrag nimmt ein label, einen path sowie optional icon, description und tag entgegen. kind (dropdown, product, version oder language) ist ein Hinweis darauf, wie der Selektor verwendet wird; alle stellen dasselbe Dropdown dar.

Ist Versionierung konfiguriert, stellt Blume automatisch einen Versions-Selektor dar – deklarierst du hier einen eigenen kind: "version"-Selektor, ersetzt er den automatischen, sodass selbstgebaute Setups weiterhin funktionieren.

Hervorgehobene Links

Hefte Links an den oberen Rand der Seitenleiste, über alle Abschnitte – ein Blog, ein Changelog, eine Kontakt- oder Supportseite, die immer nur einen Klick entfernt sein sollte. Anders als der generierte Baum sind hervorgehobene Links nicht nach Tab eingegrenzt: Sie erscheinen auf jeder Route und bei jedem Breakpoint.

navigation: {
  featured: [
    { label: "Blog", href: "https://example.com/blog", icon: "newspaper" },
    { label: "Contact", href: "/contact", icon: "headphones" },
  ],
}

Jeder Link nimmt ein label, ein href und optional ein icon entgegen (ein Name eines eingebauten Symbols, ein Bildpfad bzw. eine Bild-URL oder ein Inline-SVG – wie überall sonst auch). Ein href kann überallhin verweisen: Eine externe URL öffnet sich in einem neuen Tab, während eine interne Route (/contact) zur Build-Zeit gegen deine Seiten geprüft wird und dich warnt, wenn nichts übereinstimmt.

Für volle Kontrolle listest du explizite Einträge in navigation.sidebar auf – ein bloßes Array ist eine Kurzform für sidebar.items, und die Objektform kombiniert sie mit einem globalen display. Sind Einträge gesetzt, verwendet Blume sie unverändert und überspringt die Generierung aus dem Dateisystem:

navigation: {
  sidebar: [
    "/", // a page, referenced by route
    {
      label: "Guides", // a group
      collapsed: false,
      items: ["/configuration", "/configuration/theming"],
    },
    { label: "GitHub", href: "https://github.com/owner/repo" }, // an external link
  ],
}

Jeder Eintrag ist eine Seitenroute (eine Zeichenkette), eine Gruppe (label + items) oder ein Link (label + href). Gruppen können verschachtelt werden, den globalen display-Modus überschreiben und collapsed starten.

Header-Aktionen

navigation.actions platziert schlichte Links im Header, links neben den Symbol-Buttons, und navigation.cta ist der eine gefüllte Button:

navigation: {
  actions: [{ href: "/changelog", label: "Changelog" }],
  cta: { href: "https://example.com/signup", label: "Start free" },
}

cta ist mit Absicht Singular – ein Doku-Header hat Platz für genau eine Sache, zu der Lesende aufgefordert werden, und eine Reihe von Buttons fordert zu gar nichts auf. Sekundäre Links gehören in actions – oder in featured, wenn sie stattdessen bei der Seitenleiste sitzen sollen.

Ein http(s)- oder protokollrelatives href öffnet sich in einem neuen Tab; eine Route bleibt im Tab und wird – wie ein featured-Link – zur Build-Zeit gegen deine Seiten geprüft. Eine Seite, die von einer anderen App auf demselben Host ausgeliefert wird (etwa /signup auf dem Produkt), solltest du daher als absolute URL schreiben. actions werden unterhalb des sm-Breakpoints ausgeblendet, wo der Header nur noch Platz für das Logo und den Navigations-Umschalter hat. cta wird dort ebenfalls ausgeblendet – außer auf einer Seite ohne Navigations-Umschalter, etwa einer Landing-Page mit PageLayout ohne Tabs, wo er bleibt, da ihn auf einem Smartphone sonst nichts sichtbar machen kann.

Repository-Link

Wenn du github in deiner Konfiguration setzt, zeigt Blume ein GitHub-Symbol im Header – neben dem Theme-Umschalter –, das auf dein Repository verlinkt. Es ist standardmäßig aktiviert; blende es mit navigation.repo aus:

navigation: {
  repo: false, // hide the header GitHub link (default: true)
}

Der Link erscheint nur, wenn github konfiguriert ist, sodass Projekte ohne Repository so oder so nicht betroffen sind.

repo nimmt außerdem eine absolute URL entgegen, die das Zeichen im Header auf einen beliebigen Ort auf GitHub verweisen lässt:

navigation: {
  repo: "https://github.com/acme",
}

Das ist für ein Projekt gedacht, dessen Doku-Repository privat ist. github steuert den Bearbeiten-Link pro Seite, das Zeichen im Header und das Repository im Agenten-Manifest gemeinsam, sodass ein solches Projekt github ungesetzt lassen muss – und eine URL sorgt dafür, dass trotzdem ein Zeichen angezeigt wird, das auf etwas Öffentliches verweist. Das Symbol bleibt das GitHub-Zeichen, ein Link auf einen anderen Host gehört daher in actions.

Breadcrumbs und Seitennavigation

Diese ergeben sich kostenlos aus dem Seitenleistenbaum – ohne Konfiguration:

Breadcrumbs zeigen die übergeordnete Gruppe der aktuellen Seite über dem Titel.
Zurück- und Weiter-Links am Fuß jeder Seite folgen der Reihenfolge in der Seitenleiste und überspringen ausgeblendete Seiten.

Auf dieser Seite

Aus den ##- und ###-Überschriften jeder Seite wird automatisch eine Gliederung in der rechten Spalte erzeugt, damit lange Seiten überschaubar bleiben. Auf schmaleren Bildschirmen, wo die rechte Spalte ausgeblendet ist, klappt sie zu einem „Auf dieser Seite“-Dropdown über dem Inhalt zusammen.

Seitenaktionen

Unter dem Inhaltsverzeichnis zeigt jede Seite eine Reihe von Schnellaktionen:

Auf GitHub bearbeiten – verlinkt direkt auf die Quelldatei. Erscheint, sobald du github in deiner Konfiguration setzt.
Nach oben scrollen – kehrt sanft an den Anfang langer Seiten zurück.
Feedback geben – öffnet ein vorausgefülltes GitHub-Issue mit optionaler Reaktion und Notiz (benötigt ebenfalls github).

Andere übergeben die Seite an KI-Tools – Als Markdown kopieren und Im Chat öffnen – beschrieben unter KI.

Mit aktiviertem export ermöglicht eine Export-Aktion Lesenden zusätzlich, die Seite als PDF oder EPUB herunterzuladen.