Suche

Clientseitige Suche, die ohne API-Schlüssel sofort funktioniert, plus optionale gehostete und semantische Backends, zu denen du wechseln kannst, wenn deine Doku wächst.

Blume liefert lokale Suche ohne gehostete Infrastruktur und ohne API-Schlüssel. Sie läuft im Browser, funktioniert sowohl in blume dev als auch in blume build und indexiert nur deine echten Inhalte — Navigationselemente und ausgeschlossene Seiten werden übersprungen. Wenn du sie irgendwann überwachsen hast, kannst du zu einem gehosteten oder semantischen Backend wechseln, ohne dass sich Aussehen oder Verhalten der Suche ändern — nur der search.provider, den du konfigurierst, ändert sich.

Blume erreicht Parität mit dem Anbieterangebot von Fumadocs: Orama, FlexSearch, Algolia, Orama Cloud, Typesense und Mixedbread (dazu Pagefind). In dein Projekt wird nur das SDK des konfigurierten Anbieters installiert, sodass die Wahl eines Backends nie die anderen mitzieht.

Suche verwenden

Öffne die Suche mit ⌘K (oder Ctrl K), oder drücke /, wenn du gerade nicht in einem Feld tippst. Esc schließt sie, und ⌘J (oder Ctrl J) blendet die Ergebnisvorschau ein und aus.

Suchanfragen treffen auf Titel, Beschreibungen und Fließtext von Seiten, wobei Titeltreffer am höchsten und Beschreibungen über dem Fließtext bewertet werden.

Beliebte Seiten

Bevor ein Leser eine Suchanfrage tippt, zeigt der Suchdialog eine Beliebt-Liste. Standardmäßig sind das die ersten sechs Seiten der Seitenleiste — was auf Websites mit mehreren Tabs oft den falschen Bereich hervorhebt. Hefte stattdessen die gewünschten Links an:

search: {
  popular: [
    { href: "/guides/getting-started", icon: "rocket", label: "Getting started" },
    { href: "/guides/install", icon: "download", label: "Install" },
    { href: "/concepts/overview", label: "Overview" },
  ],
},

Jeder Eintrag benötigt ein href (interne Route oder externe URL) und ein label, dazu optional ein icon — der Name eines integrierten Icons, ein Bildpfad bzw. eine Bild-URL oder ein Inline-SVG (dieselben Eingaben wie bei Nav-Icons), standardmäßig ein Datei-Symbol. Lass popular weg oder leer, um den Fallback auf die Seitenleiste beizubehalten.

Schreibe href so, als wäre die Website im Stammverzeichnis eingehängt — ein basePath wird für dich angewendet, genau wie bei navigation.featured. Externe URLs werden unverändert durchgereicht.

Was indexiert wird

Für Orama, FlexSearch, Algolia, Orama Cloud und Typesense — sowie für das search_docs-Tool des MCP-Servers — indexiert Blume den Titel, die Beschreibung und den auf reinen Text reduzierten Fließtext jeder Seite: Codeblöcke, Bilder und Markup werden entfernt, damit die Ergebnisse relevant bleiben. Diese Indizes werden aus deinen Quelldateien erstellt und sind daher in der Entwicklung und in der Produktion identisch. Pagefind indexiert stattdessen das gebaute HTML, und Mixedbread synchronisiert dein rohes Markdown, sodass beide immer auch Code durchsuchen.

Wenn deine Doku bei durchsuchbaren Begriffen wie Optionen, Methoden oder Fehlernamen auf Codebeispiele setzt, nimm eingefassten Code ausdrücklich in die quellbasierten Indizes auf:

search: {
  indexing: {
    includeCodeBlocks: true,
  },
},

Der Inhalt und der Titel jedes Code-Fences (blume.config.ts oben) werden durchsuchbar; die Sprache und die Fence-Marker nicht. Auf .mdx-Seiten liest der Index Komponenten als den Text, den sie anzeigen — den Titel einer Card, das Label eines Tab, die Beschreibungen einer TypeTable — und nutzt dabei dieselben Serializer wie die Agent-Oberflächen, sodass ein ai.markdownComponents-Eintrag auch deine eigenen Komponenten abdeckt. Auf Pagefind oder Mixedbread hat die Option keine Wirkung. Rechne damit, dass der Index mit deinen eingefassten Inhalten wächst — der Client-Index wird an jeden Leser ausgeliefert, gehostete Anbieter begrenzen die Datensatzgröße (Algolia weist den Synchronisierungs-Batch zurück, wenn der Datensatz einer Seite das Limit deines Tarifs überschreitet, und der bisherige Index bleibt aktiv), und ein Treffer innerhalb eines Fences zeigt im Ergebnisauszug flach dargestellten Code.

Auf einer versionierten Website beziehen sich die Ergebnisse standardmäßig auf die gerade angesehene Version, mit einem „Alle Versionen“-Schalter in der Fußzeile des Dialogs (der pro Leser gemerkt wird). Treffer aus anderen Versionen nennen ihre Version in der Zeile. Orama, FlexSearch, Algolia und Typesense berücksichtigen diese Eingrenzung — gehostete Datensätze tragen eine version-Facette, wobei die aktuelle Doku als "current" hochgeladen wird —, während Pagefind ohne Eingrenzung bleibt, passend zu seinem Verhalten bei Sprachen.

Anbieter

Die clientseitigen Anbieter kommen ohne Schlüssel aus und benötigen keine zusätzliche Konfiguration. Die gehosteten nehmen öffentliche Zugangsdaten in blume.config.ts entgegen (die gefahrlos an den Browser ausgeliefert werden können) und lesen ihren geheimen Admin-Schlüssel zur Buildzeit aus einer Umgebungsvariablen — das Geheimnis landet nie in der Konfiguration oder im Client-Bundle.

Orama (Standard)

Blumes Standard-Engine. Sie erstellt einen JSON-Index, der unter /blume-search.json ausgeliefert wird, und fragt ihn im Browser ab — sofort, clientseitig und in blume dev live beim Bearbeiten. Keine Schlüssel, kein Dienst.

search: {
  provider: "orama", // default
}

Nicht-lateinische Schriften

Oramas Standard-Tokenizer behält nur lateinische Grundbuchstaben, Ziffern und eine Handvoll akzentuierter Vokale, sodass Text in jeder anderen Schrift — Japanisch, Chinesisch, Koreanisch und Thai, aber ebenso Russisch, Griechisch, Hebräisch und Hindi — sonst überhaupt keine Treffer liefern würde. Blume erledigt das für dich: Wenn i18n.defaultLocale auf eine nicht-lateinische Schrift verweist, wechselt der Index zu einem wortsegmentierenden Tokenizer (aufgebaut auf dem in Browser und Node nativ verfügbaren Intl.Segmenter). Die Sprache deiner Website zu deklarieren, ist alles, was nötig ist:

i18n: {
  defaultLocale: "ja",
  locales: [{ code: "ja", label: "日本語" }],
}

Derselbe Tokenizer bedient den Suchdialog, das search_docs-Tool des MCP-Servers und die Fundierung von Ask AI. Entscheidend ist die Schrift, nicht der Sprachname — az-Cyrl wird segmentiert, sr-Latn nicht — und für den gesamten Index entscheidet die Standardsprache: Auf einer mehrsprachigen Website teilen sich alle Seiten den Tokenizer der Standardsprache. Bei einer nicht-lateinischen Standardsprache ist das unbedenklich, denn lateinische Wörter überstehen die Segmentierung unverändert, sodass Seiten auf Englisch neben der Standardsprache durchsuchbar bleiben. Umgekehrt gilt das nicht: Nicht-lateinische Übersetzungen auf einer Website mit lateinischer Standardsprache sind nicht durchsuchbar. Auch Sprachen in lateinischer Schrift, die stark auf Diakritika setzen (Vietnamesisch oder Serbisch in lateinischer Schrift), schneiden beim Standard-Tokenizer schlechter ab, der nur wenige akzentuierte Vokale zusammenfasst und Wörter an allen übrigen trennt.

Bei Japanisch und Chinesisch geht es noch einen Schritt weiter. Segmentierung allein indexiert einen zusammengesetzten Begriff als seine Bestandteile — 資金決済法 als 資金, 決済 und 法 — wodurch eine Seite, die jeden Bestandteil irgendwo erwähnt, die Seite überflügeln kann, um die es beim Begriff eigentlich geht. Han, Hiragana und Katakana werden deshalb als überlappende Zeichenpaare indexiert, und Abfragen auf diesen Indizes bevorzugen Seiten, die die Paare eines Begriffs gemeinsam tragen, und lockern auf Treffer mit beliebigen Paaren, wenn keine Seite alle trägt — so liefert auch das Tippen eines ganzen Satzes noch die passendsten Seiten. Koreanisch und Thai behalten ihre segmentierten Wörter.

FlexSearch

Eine zweite schlüssellose, clientseitige Option. Sie verwendet denselben /blume-search.json-Index wieder, den Orama ausliefert, und baut im Browser einen FlexSearch-Dokumentindex auf. Funktioniert in blume dev und blume build.

FlexSearch hat keinen vergleichbaren Segmentierungs-Hook, daher solltest du für Websites in nicht-lateinischer Schrift Orama (den Standard) oder Pagefind bevorzugen, dessen pagefind_extended-Binary eine breite Palette von Sprachen indexiert und Chinesisch, Japanisch und Koreanisch nativ segmentiert.

search: {
  provider: "flexsearch",
}

Pagefind

Für sehr große Dokumentationen kannst du dich für Pagefind entscheiden. Es indexiert dein gebautes HTML und lädt den Index bei Bedarf in Shards, sodass die anfängliche Nutzlast winzig bleibt, egal wie groß die Website wird.

search: {
  provider: "pagefind",
}

Pagefind läuft nur während blume build, daher ist die Suche mit diesem Anbieter in blume dev nicht verfügbar.

Algolia

Der Browser fragt Algolia direkt mit deinem reinen Suchschlüssel ab. Jedes blume build ersetzt den Index mithilfe des Admin-Schlüssels aus ALGOLIA_ADMIN_API_KEY (der Build warnt und überspringt den Upload, wenn er nicht gesetzt ist). Bei jeder Synchronisierung wird der gesamte Index ersetzt, sodass gelöschte oder umbenannte Seiten nicht als veraltete Ergebnisse zurückbleiben.

search: {
  provider: "algolia",
  algolia: {
    appId: "YOUR_APP_ID",
    indexName: "docs",
    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
  },
}

Orama Cloud

Gehostetes Orama. Der Browser fragt deinen Index-Endpunkt mit dem öffentlichen API-Schlüssel ab; blume build schiebt Datensätze mit ORAMA_PRIVATE_API_KEY in den Index. Setze indexId, um die Synchronisierung zu aktivieren.

search: {
  provider: "orama-cloud",
  oramaCloud: {
    endpoint: "https://cloud.orama.run/v1/indexes/your-index",
    apiKey: "YOUR_PUBLIC_API_KEY",
    indexId: "your-index-id", // for the build-time sync
  },
}

Typesense

Selbst gehostetes oder Cloud-Typesense. Der Browser fragt die Collection mit dem reinen Suchschlüssel ab; blume build erstellt die Collection neu und importiert Dokumente mit TYPESENSE_ADMIN_API_KEY. Die Collection wird bei jeder Synchronisierung verworfen und neu aufgebaut, damit gelöschte oder umbenannte Seiten nicht als veraltete Ergebnisse zurückbleiben — wenn du die Einstellungen der Collection von Hand feinabstimmst, wende sie nach einem Build erneut an.

search: {
  provider: "typesense",
  typesense: {
    host: "xyz.a1.typesense.net",
    collection: "docs",
    searchApiKey: "YOUR_SEARCH_ONLY_KEY", // public
    // port + protocol default to 443 / https
  },
}

Mixedbread

Semantische Suche über Mixedbread. Anfragen werden über einen generierten /api/search-Endpunkt geleitet, der deinen Schlüssel hält, weshalb dieser Anbieter Server-Output erfordert (deployment.output: "server"). Der Endpunkt liest MIXEDBREAD_API_KEY. Synchronisiere deine Inhalte im Build mit der Mixedbread-CLI in den Store, z. B. mxbai vs sync <STORE_ID> ./content --ci.

search: {
  provider: "mixedbread",
  mixedbread: {
    storeId: "YOUR_STORE_ID",
  },
}

Suche deaktivieren

search: {
  provider: "none",
}

Seiten ausschließen

Es werden nur indexierbare Seiten durchsucht. Eine Seite bleibt aus dem Index heraus, wenn sie search.exclude im Frontmatter setzt:

search:
  exclude: true

Versteckte Seiten sind ebenfalls standardmäßig ausgeschlossen. Um sie trotzdem zu indexieren, aktiviere es ausdrücklich:

search: {
  indexing: { includeHiddenPages: true },
}