Konfigurationsdatei

Jede Option in blume.config.ts, von Website-Metadaten und Inhaltsquellen bis zu den Links, die zu den einzelnen Konfigurationsanleitungen der jeweiligen Funktionen führen.

Blume liest blume.config.ts aus dem Stammverzeichnis deines Projekts. Umschließe deine Konfiguration mit defineConfig, um Autovervollständigung und Typprüfung zu erhalten — jedes Feld ist optional und hat einen sinnvollen Standardwert.

import { defineConfig } from "blume";

export default defineConfig({
  title: "My Docs",
  description: "Documentation for my project.",
});

Ein vollständiges Beispiel

Ein umfassenderes Beispiel, das die gängigsten Optionen abdeckt (den Rest findest du in der Anleitung zur jeweiligen Funktion):

import partytown from "@astrojs/partytown";
import { defineConfig } from "blume";
import { orama } from "blume/search";

export default defineConfig({
  // Site
  title: "My Docs",
  description: "Documentation for my project.",
  logo: "/logo.svg",

  // Astro integrations — installed and versioned by this site
  integrations: [partytown()],

  // Content
  content: {
    root: "docs",
  },

  // Theme — see the Theming guide
  theme: {
    accent: "teal",
    radius: "md",
    mode: "system",
  },

  // Search — an adapter from "blume/search"; see the Search guide
  search: orama(),

  // Markdown features
  markdown: {
    imageZoom: true,
    externalLinks: false, // open https:// links in a new tab
    code: {
      icons: true, // language icon in the code-block header
      wrap: false, // wrap long lines instead of scrolling
      theme: {
        light: "github-light", // bundled name or custom Shiki theme object
        dark: "github-dark",
      },
    },
  },

  // Agents — llms.txt, MCP, the AI catalog; see the Discoverability section
  agents: {
    llmsTxt: true,
    // AI Catalog / ARD manifest at /.well-known/ai-catalog.json (needs deployment.site)
    catalog: true,
    // Your site's agent skill at /skill.md (needs deployment.site)
    skillMd: true,
    // MCP server (needs server output)
    mcp: {
      enabled: false,
      route: "/mcp",
    },
  },

  // SEO — OG images, feeds, sitemap, structured data; see the Discoverability section
  seo: {
    og: { enabled: true },
    rss: { enabled: true, types: ["blog", "changelog"] },
    sitemap: true,
    robots: true,
    structuredData: true,
  },

  // Deployment — a static build here; see the Deployment guide for host adapters
  deployment: {
    site: "https://docs.example.com",
  },
});

Website

Logo

Verweise mit logo auf eine SVG-Datei, und Blume bindet sie inline ein, sodass ein Logo mit currentColor automatisch dem hellen und dunklen Theme folgt:

logo: "/logo.svg",

Die SVG-Datei kann im Stammverzeichnis deines Projekts oder in public/ liegen. Die Marke besteht aus einer Bildmarke (image) plus einer Wortmarke (text); in der Objektform kannst du beide unabhängig voneinander festlegen:

logo: {
  image: "/logo.svg", // string, or { light, dark, alt } for themed raster art
  text: "Acme",       // wordmark beside the mark
  href: "/",          // overrides the brand link (defaults to "/")
},

image nimmt denselben Wert wie die Kurzform entgegen — einen einzelnen Pfad oder { light, dark, alt } für getrennte helle/dunkle Grafiken (Rasterbilder müssen in public/ liegen).

href ist ein Pfad in der Standardsprache, genau wie ein Tab-Pfad: Auf einer mehrsprachigen Website wandert der Markenlink in die Sprache der Leserin bzw. des Lesers (/ wird unter /en/… zu /en), sofern diese Sprache die Route bereitstellt — ein Klick auf das Logo verlässt also nicht die Sprache, in der gerade gelesen wird. Eine Route, die nur die Standardsprache bereitstellt — eine benutzerdefinierte Seite oder der generierte Changelog-Index —, behält ihren eigenen Pfad, statt auf eine lokalisierte URL zu verweisen, die einen 404-Fehler liefern würde. Eine absolute URL wird unverändert verwendet.

text steuert die Wortmarke unabhängig von der Bildmarke:

• Lässt du text weg, verwendet die Marke den title deiner Website (Standardverhalten).
• Setze text: "", um nur die Bildmarke anzuzeigen — praktisch, wenn das Logobild die Wortmarke bereits enthält. Screenreader lesen den Markenlink dann anhand des alt-Texts des Bildes vor — oder anhand des title deiner Website, wenn es keinen hat.
• Setze text ohne image für ein reines Text-Logo.

Favicon

Es gibt keine Favicon-Option — Blume erkennt es automatisch anhand des Dateinamens, so wie Next.js es tut. Lege eine icon- oder favicon-Datei (.svg, .png oder .ico) in das Stammverzeichnis deines Projekts oder in das Verzeichnis public/, und sie wird zum Symbol im Browser-Tab:

my-docs/
├─ blume.config.ts
├─ icon.png          ← picked up automatically
└─ docs/

Sind mehrere vorhanden, gewinnt SVG vor PNG vor ICO, und eine Datei in public/ wird gegenüber einer im Stammverzeichnis bevorzugt. Findet Blume kein Icon, greift es auf die eigene Bildmarke zurück.

Eine dunkle Bildmarke verschwindet vor dunkler Browser-Oberfläche, deshalb kannst du eine zweite Datei für den Dunkelmodus mitliefern. Lege eine -dark-Geschwisterdatei neben deine Icon-Datei — gleicher Name, gleiches Verzeichnis, mit -dark vor der Dateiendung (icon.png → icon-dark.png) — und Blume gibt beide Icons hinter einer prefers-color-scheme-Media-Query aus, plus ein einfaches helles Tag für Browser und Crawler, die Media Queries bei Icons ignorieren:

my-docs/
├─ blume.config.ts
├─ icon.png          ← light mode
├─ icon-dark.png     ← dark mode
└─ docs/

Verwendet wird nur die Geschwisterdatei des Icons, das Blume ausgewählt hat — eine -dark-Datei mit einem anderen Namen bleibt unbeachtet, sodass sich keine unbeteiligte Datei versehentlich mit deiner Bildmarke paaren kann. Die dunkle Datei ist optional; bei nur einem Icon gibt Blume wie bisher ein einzelnes Tag aus. Blumes eigene Fallback-Bildmarke bringt beide Varianten mit.

Apple-Touch-Icon

Das Symbol, das iOS verwendet, wenn jemand deine Website zum Home-Bildschirm hinzufügt, wird auf dieselbe Weise erkannt. Lege eine apple-icon-Datei (.png, .jpg oder .jpeg) — oder eine apple-touch-icon.png, den Namen, den die meisten Favicon-Generatoren ausgeben — in das Stammverzeichnis deines Projekts oder in das Verzeichnis public/, und Blume richtet <link rel="apple-touch-icon"> für dich ein. Es gibt keinen Standardwert; wird keine Datei gefunden, wird kein Tag ausgegeben.

my-docs/
├─ blume.config.ts
├─ apple-icon.png     ← picked up automatically
└─ docs/

Lege die Datei in public/ statt in das Stammverzeichnis des Projekts: iOS ignoriert die Inline-Daten-URI, die Blume für ein Icon im Stammverzeichnis verwendet, sodass nur eine Datei in public/ (ausgeliefert unter /apple-icon.png) zuverlässig auf den Home-Bildschirm gelangt. Anders als beim Favicon gibt es hier keine -dark-Geschwisterdatei — iOS ignoriert Media Queries bei Home-Bildschirm-Icons, eine dunkle Variante könnte also nie ausgeliefert werden.

Banner

Zeige eine websiteweite Ankündigungsleiste über dem Header an. Übergib eine Zeichenkette oder ein Objekt mit einem Link und einer Schließen-Schaltfläche:

banner: "Docs are in beta — expect changes.",

banner: {
  content: "Version 2.0 is here!",
  link: { text: "Read the release notes", href: "/changelog" },
  dismissible: true,
  id: "v2",
},

Ist dismissible aktiviert, zeigt die Leiste eine Schließen-Schaltfläche und bleibt für diese Besucherin bzw. diesen Besucher danach ausgeblendet. Der Schlüssel für das Ausblenden basiert standardmäßig auf dem Inhaltstext, sodass eine Bearbeitung der Nachricht das Banner zurückbringt; setze eine feste id, damit es über Bearbeitungen hinweg ausgeblendet bleibt.

Auf einer mehrsprachigen Website akzeptieren content und der text des Links auch eine Zuordnung von Sprachcode zu Text. Jede Seite zeigt den Eintrag ihrer eigenen Sprache an und greift andernfalls auf den der Standardsprache zurück, und der Link wandert in die Sprache der Leserin bzw. des Lesers, sofern diese Sprache die Seite bereitstellt:

banner: {
  content: { en: "Version 2.0 is here!", fr: "La version 2.0 est là !" },
  link: {
    text: { en: "Read the release notes", fr: "Lire les notes de version" },
    href: "/changelog",
  },
},

Bei einem übersetzten Banner basiert der Schlüssel für das Ausblenden auf dem Text der Standardsprache, sodass ein einmaliges Schließen es in jeder Sprache ausblendet.

Footer

Jede Seite endet mit einem Footer: einer Zeile, so hoch wie der Header, mit deinen Links auf der einen Seite, Social-Profil-Icons auf der anderen und einer Copyright-Zeile mittig dazwischen. Der Footer ist der einzige Ort, an dem Blume deine Social-Profile und dein Repository verlinkt, deshalb steht das github-Repository unter den Icons an erster Stelle, sofern es gesetzt ist. footer ergänzt den Rest:

footer: {
  copyright: "© 2026 Acme, Inc.",
  links: [
    { label: "Pricing", href: "https://acme.dev/pricing" },
    { label: "Changelog", href: "/changelog" },
    { label: "Blog", href: "https://acme.dev/blog" },
  ],
  socials: {
    x: "https://x.com/acme",
    discord: "https://discord.gg/acme",
  },
},

copyright ist reiner Text, schreibe also © direkt statt ©. Für eine Jahreszahl, die sich selbst aktuell hält, verwende ein Template-Literal: `© ${new Date().getFullYear()} Acme, Inc.`. links erscheinen in der Reihenfolge, in der du sie angibst. Schreibe interne Links so, als wäre die Website im Stammverzeichnis eingehängt; ein externer Link öffnet sich in einem neuen Tab. Auf einer mehrsprachigen Website können copyright und ein label jeweils eine Zuordnung von Sprachcode zu Text sein, und ein interner Link wandert in die Sprache der Leserin bzw. des Lesers, sofern diese Sprache die Seite bereitstellt. socials ordnet einer Plattform ihre Profil-URL zu, und die Icons erscheinen in der Reihenfolge, in der du sie angibst. Die verfügbaren Plattformen sind bluesky, discord, facebook, github, hacker-news, instagram, linkedin, medium, podcast, reddit, slack, telegram, threads, website, x und youtube. Ein github-Eintrag unter socials ersetzt den Repository-Link; blende diesen Link mit navigation.repo aus.

Eine Website ohne Copyright, Links, Profile oder Repository hat keinen Footer. Benutzerdefinierte Seiten, die auf PageLayout aufbauen, zeigen ihn ebenfalls an, sofern sie nicht den eigenen footer-Slot des Layouts befüllen. Um ihn vollständig zu ersetzen, überschreibe den Footer-Layout-Slot.

Inhalte

Wo deine Inhalte liegen und wie Blume sie findet. Unter Seiten erfährst du, wie aus Dateien Routen werden.

content: {
  root: "docs",
}

Statische Assets liegen in public/ — eine Datei unter public/logo.png wird unter /logo.png ausgeliefert, sodass eine Referenz wie ![](/images/create.png) auf public/images/create.png verweist. Bilder, die über einen relativen Pfad referenziert werden (![](./diagram.png)), liegen stattdessen neben deinen Inhalten und werden beim Build optimiert.

Bilder

Lokale Bilder, die über einen relativen Pfad referenziert werden, werden beim Build automatisch optimiert — komprimiert, in WebP konvertiert und mit intrinsischen width/height-Attributen versehen, damit das Layout beim Laden nicht springt. Es gibt nichts zu konfigurieren; Hinweise zum Verfassen findest du unter Links und Bilder.

Externe Bilder werden standardmäßig unverändert ausgeliefert. Damit Blume sie ebenfalls beim Build herunterlädt und optimiert, autorisiere ihre Hosts:

image: {
  domains: ["cdn.example.com"],
  remotePatterns: [{ protocol: "https", hostname: "**.example.com" }],
}

Frontmatter

Das Frontmatter einer Seite wird streng validiert — ein unbekannter Schlüssel lässt den Build fehlschlagen, sodass Tippfehler früh auffallen. Um projektspezifische Metadaten zu hinterlegen (eine verantwortliche Person, ein Prüfdatum), deklariere die zusätzlichen Schlüssel unter frontmatter.extend, jeweils zugeordnet zu einem von dir bereitgestellten Schema:

import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  frontmatter: {
    extend: {
      owner: z.string(),
      reviewedAt: z.coerce.date().optional(),
    },
  },
});

Jede Standard-Schema-Bibliothek funktioniert — Zod (in der Version, die dein Projekt installiert), Valibot, ArkType. Schlüssel außerhalb der Erweiterung bleiben streng validiert, das Erkennen von Tippfehlern ändert sich also nicht. Zur Validierungssemantik siehe Benutzerdefinierte Schlüssel.

Schlüssel unter extend gelten websiteweit. Um Schlüssel nur auf Seiten eines Inhaltstyps vorzuschreiben — der status eines RFCs, der service eines Runbooks — deklariere sie stattdessen pro Typ unter content.types:

import { defineConfig } from "blume";
import { z } from "zod";

export default defineConfig({
  content: {
    types: {
      rfc: {
        facets: ["domain", "status"],
        frontmatter: {
          domain: z.string(),
          status: z.enum(["draft", "review", "enforced"]),
        },
      },
    },
  },
});

Ein Schlüssel kann websiteweit oder pro Typ deklariert werden, nicht beides. Wie die Zuordnung aufgelöst wird, erfährst du unter Schlüssel pro Typ.

facets benennt die benutzerdefinierten Schlüssel, deren Werte zu filterbaren Metadaten werden: Sie werden mit den Suchdokumenten mitgeführt (blume-search.json und der MCP-Index), und die MCP-Tools akzeptieren eine filters-Eingabe, die gegen sie abgeglichen wird, sodass ein Agent zum Beispiel nur enforced-RFCs in der Domäne architecture abrufen kann. Jedes Facet muss ein deklarierter benutzerdefinierter Schlüssel sein — pro Typ oder websiteweit — und nur Zeichenketten-Werte (oder in Zeichenketten umgewandelte Zahlen/Booleans) werden facettiert.

GitHub

Verweise Blume mit github auf dein Repository. Das versorgt den Repository-Link im Footer sowie die Seitenaktion Edit on GitHub:

github: {
  owner: "acme",
  repo: "docs",
}

GitHub Enterprise

Dokumentationen, deren Repository auf einer GitHub-Enterprise-Instanz liegt, setzen host, und jeder aus dem Repository abgeleitete Link — die Bildmarke im Header, Bearbeitungslinks, das Agenten-Manifest — verweist dann auf diese Instanz statt auf die öffentliche Website:

github: {
  host: "https://github.acme.com",
  owner: "acme",
  repo: "docs",
}

Die REST-API-Basis, die <GithubInfo> abfragt, wird aus host abgeleitet: Ein Enterprise-Cloud-Tenant mit Datenresidenz (acme.ghe.com) wird über seine api.-Subdomain ausgeliefert, und jeder andere Host wird als Enterprise Server behandelt (/api/v3). Setze api explizit, wenn deine Instanz woanders liegt.

Zuletzt geändert

Zeige am Ende jeder Seite eine Zeile „Zuletzt aktualisiert am …“ an. Standardmäßig deaktiviert; setze lastModified auf "git", um das Datum jeder Seite aus ihrer Git-Historie abzuleiten:

lastModified: "git",

Die Git-Quelle liest den jüngsten Commit, der die jeweilige Datei berührt hat, funktioniert also in jedem Git-Repository — auch in Monorepos — und benötigt die Historie des Repositorys zur Build-Zeit. Sie folgt Umbenennungen, so wie es git log --follow tut: Wird page.md in page.mdx umbenannt oder eine Datei in einen anderen Ordner unterhalb desselben Inhalts-Stammverzeichnisses verschoben, bleibt das Datum der Seite erhalten, solange der Commit ihren Inhalt unverändert lässt. Eine Umbenennung, bei der die Datei zugleich bearbeitet wird, datiert die Seite auf diesen Commit — ebenso das Hereinverschieben einer Datei von außerhalb des Inhalts-Stammverzeichnisses. CI-Plattformen checken üblicherweise einen flachen Klon aus, wodurch die meisten Daten stillschweigend verloren gehen (der Build warnt in diesem Fall mit BLUME_SHALLOW_GIT_HISTORY): Setze auf Vercel die Umgebungsvariable VERCEL_DEEP_CLONE=true; bei actions/checkout setze fetch-depth: 0. Das seiteneigene lastModified-Frontmatter gewinnt immer, was praktisch ist, um ein Datum festzuschreiben oder für Dateien, die noch nicht committet sind:

---
title: My page
lastModified: 2026-06-20
---

Ist die Funktion aktiviert, wird das Datum außerdem als schema.org-dateModified in den strukturierten Daten der Seite ausgegeben.

Datumsformat

Sowohl der Stempel „Zuletzt aktualisiert“ als auch die Zeitleiste des Changelogs rendern ihre Daten über dasselbe dateFormat, damit sie sich gleich lesen. Daten werden immer in der Sprache der Website gerendert; dateFormat steuert die Form. Standardmäßig wird die lange Form verwendet (July 21, 2026, 2026年7月21日):

dateFormat: { dateStyle: "long" },

dateFormat wird direkt an die Optionen von Intl.DateTimeFormat durchgereicht. Verwende eine dateStyle-Voreinstellung für eine bestimmte Länge:

dateFormat: { dateStyle: "medium" },

Oder die einzelnen Komponentenfelder für einen numerischen Hausstil wie 2026/07/21:

dateFormat: { year: "numeric", month: "2-digit", day: "2-digit" },

timeZone, calendar und numberingSystem ändern die Form nicht: Ein dateFormat, das nur diese setzt, behält die lange Form bei.

SEO und Agents

Metadaten, Open-Graph-Bilder, RSS-Feeds, JSON-LD, die Sitemap und robots.txt liegen unter seo; llms.txt, rohes Markdown, die JSON-API, der MCP-Server und die Discovery-Manifeste liegen unter agents. Beide werden Seite für Seite im Abschnitt Auffindbarkeit behandelt, der Suchmaschinen und KI-Agents als zwei Zielgruppen derselben maschinenlesbaren Schicht betrachtet. Die modellbasierten Funktionen für Lesende — der Assistent und die Aktion „Open in chat“ — liegen unter ai.

seo: {
  og: { enabled: true },
  rss: { enabled: true, types: ["blog", "changelog"] },
  sitemap: true,
  robots: true,
  structuredData: true,
}

Diese Funktionen entfalten ihre volle Wirkung mit einer absoluten deployment.site für vollständige URLs.

Inhaltsverzeichnis

Die Gliederung „Auf dieser Seite“ ist standardmäßig aktiviert und listet H2–H3-Überschriften auf. Schalte sie mit toc ab oder ändere den Überschriftenbereich:

export default defineConfig({
  toc: false, // hide it everywhere
});

Oder schränke stattdessen den Überschriftenbereich ein:

export default defineConfig({
  toc: { minHeadingLevel: 2, maxHeadingLevel: 4 },
});

Seiten-Feedback

Jede Docs-Seite endet mit der Bewertung „War diese Seite hilfreich?“. Sie ist standardmäßig aktiviert; setze feedback auf false, um sie überall auszublenden:

export default defineConfig({
  feedback: false,
});

Die Antwort einer Leserin bzw. eines Lesers wird als feedback-Custom Event gesendet — mit helpful ("yes" oder "no"), path und title —, und zwar über jeden konfigurierten Analytics-Adapter, der eine Event-API besitzt, sowie als blume:track-Event auf window. Fathom, Microsoft Clarity und Hotjar erfassen nur den Namen eines Events, ohne dessen Properties — sie zählen Bewertungen also, können ein Ja aber nicht von einem Nein unterscheiden. Ohne Analytics-Adapter wird die Antwort nirgendwo erfasst, und ist die Cookie-Einwilligung aktiviert, wird die Bewertung nur Lesenden angezeigt, die Analytics erlaubt haben, da eine Antwort von allen anderen ohnehin nirgendwo ankäme. Die Frage und der Dankestext sind UI-Zeichenketten, die du mit i18n.ui übersetzen kannst.

Schriftliches Feedback

Wenn du mehr als Ja oder Nein erfahren möchtest, aktiviere Kommentare. Nach der Bewertung einer Seite erhält die Leserin bzw. der Leser ein Textfeld, um zu sagen, was geholfen hat oder was fehlt:

export default defineConfig({
  feedback: { comments: true },
});

Ein Kommentar wird als feedback_comment-Event gesendet — mit denselben Werten für helpful, path und title wie die Bewertung, plus dem comment der Leserin bzw. des Lesers (bis zu 1.000 Zeichen). Er läuft über dieselben Adapter wie die Bewertung, du liest Kommentare also dort, wo du auch deine Events liest. Anbieter begrenzen die Länge von Property-Werten, daher kann ein langer Kommentar gekürzt ankommen: Google Analytics behält 100 Zeichen, Mixpanel 255 Bytes (weniger Zeichen bei einer Schrift, die mehrere Bytes pro Zeichen benötigt, etwa Japanisch), und Vercel Web Analytics nimmt Werte bis zu 255 Zeichen entgegen, während PostHog und Segment Kommentare vollständig übernehmen. Fathom, Clarity und Hotjar erhalten überhaupt keinen Kommentartext. Plausible gruppiert identische Werte, statt jeden Kommentar einzeln aufzulisten, und eignet sich daher besser für Bewertungen als für Kommentare. Lesende können beliebigen Text in das Feld schreiben, behandle Kommentare also so, als könnten sie personenbezogene Daten enthalten.

Die Beschriftung und die Schaltfläche des Felds sind ebenfalls UI-Zeichenketten (feedback.comment und feedback.send).

Funktionsoptionen

Zu jeder dieser Optionen gibt es eine eigene Anleitung. Das Konfigurationsfeld ist der Einstiegspunkt:

Rangfolge

Einstellungen werden von der niedrigsten zur höchsten Priorität aufgelöst, sodass du nur überschreibst, was du brauchst: