Frontmatter

Alle Frontmatter-Felder, die eine Seite akzeptiert, alle optional — Titel, Beschreibung, Sidebar, SEO, Suche und der Rest, jeweils mit dem, was sie steuern.

Jede Seite akzeptiert die folgenden Frontmatter-Felder. Alle Felder sind optional.

Frontmatter ist YAML. Setz einen Wert deshalb in Anführungszeichen, wenn er einen Doppelpunkt gefolgt von einem Leerzeichen enthält, etwa description: "Setup: the easy way". Ohne Anführungszeichen liest YAML den zweiten Doppelpunkt als Beginn eines verschachtelten Schlüssels, und Blume meldet Datei und Zeile als BLUME_FRONTMATTER_INVALID.

Layout

mode legt fest, was eine Seite um ihren Inhalt herum anzeigt:

wide eignet sich für eine Seite mit breiten Tabellen oder Diagrammen, center für Release Notes oder eine Ankündigung, die von oben nach unten gelesen wird. custom behält nur den Header, etwa für eine in MDX geschriebene Landingpage, und frame behält zusätzlich die Sidebar, etwa für ein Tool oder Dashboard, das in der Navigation der Doku sitzt. Keiner der beiden Modi rendert Titel oder Beschreibung der Seite, schreib also deine eigene Überschrift. Jeder Modus bleibt in der Suche und behält seine Markdown-Kopie.

title: Welcome
mode: custom

Die Werte entsprechen denen von Mintlify. Dessen assistant-Modus, ein ganzseitiger Chat, hat keine Entsprechung.

Verwandte Seiten

related listet Seiten auf, die am Ende dieser Seite als Karten unter der Überschrift Verwandte Seiten vorgeschlagen werden:

related:
  - /guides/deployment
  - Search setup: /configuration/search
  - https://astro.build

Ein root-relativer Pfad verweist auf eine andere Seite, die die Karte mit deren Titel und Beschreibung anzeigt. Auf einer übersetzten Seite verlinkt er auf die Übersetzung, sofern es eine gibt. Ein Title: link-Eintrag legt den Titel der Karte selbst fest, und eine absolute URL verlinkt unter ihrem Hostnamen auf eine externe Website. Pfade werden wie jeder andere Link auf der Seite geprüft, sodass blume validate einen Pfad meldet, der zu keiner Seite passt. Der Schlüssel entspricht dem von Mintlify, sodass migrierte Seiten ihn unverändert behalten.

Sidebar

sidebar:
  label: Install
  order: 2
  icon: download
  badge: New
  hidden: false
  display: page

hidden entfernt die Seite aus der Sidebar und aus der Zurück/Weiter-Paginierung und damit auch aus der Sitemap, der Suche und llms.txt (siehe Versteckte Seiten). Auf der index-Seite eines Ordners entfernt es nur die eigene Zeile der Seite: Die Gruppenzeile verlinkt weiterhin auf die Seite, sodass die Zurück/Weiter-Links weiterhin durch sie hindurchführen und die Seite in der Sitemap, der Suche und llms.txt bleibt. Auf der Startseite, der index-Seite des Stammverzeichnisses, entfernt es ebenfalls nur die Zeile: Die Seite bleibt in der Sitemap, der Suche und llms.txt.

display legt den Darstellungsmodus der Ordnergruppe der Seite fest (Überschreibungen pro Gruppe) und ist nur auf der index-Seite eines Ordners in der generierten Sidebar sinnvoll — überall sonst (auf einer Nicht-Index-Seite, der eigenen index-Seite des Content-Stammverzeichnisses oder jeder Seite unter einer expliziten navigation.sidebar) gibt es keine Gruppe zu konfigurieren, und Blume warnt mit BLUME_SIDEBAR_DISPLAY_IGNORED.

SEO

seo:
  title: Install Blume
  description: Install Blume and scaffold your first project.
  image: /og/install.png
  canonical: https://acme.com/install
  noindex: false
  x:
    creator: "@jane"

noindex gibt ein robots-noindex aus, entfernt die Seite aus der Sitemap und lässt ihre strukturierten Daten weg. Ein canonical, das auf eine andere URL verweist, entfernt die Seite ebenfalls aus der Sitemap, da die Sitemap nur kanonische URLs auflistet. x.creator schreibt die Seite einem X-Account zu (twitter:creator) — etwa der Person, die einen Gastbeitrag verfasst hat. Alle Felder findest du unter Metadaten.

Suche

search:
  exclude: false
  tags: [api]
  keywords: [install, setup]
  boost: 3

exclude hält die Seite aus der Suche heraus, und tags versieht ihren Eintrag mit Labels, nach denen ein gehosteter Such-Adapter filtern kann (siehe Tags). keywords sind zusätzliche Begriffe, über die die Seite neben ihrem eigenen Text gefunden wird. boost multipliziert die Relevanz der Seite: Werte über 1 ranken sie höher, Werte unter 1 niedriger. Mehr dazu findest du unter Ranking.

KI

ai:
  exclude: true

ai.exclude hält die Seite aus llms.txt und llms-full.txt und aus der Seitenübersicht im Skill deiner Website heraus. Die Seite wird trotzdem gerendert, bleibt in der Suche, im MCP-Server und in der JSON-API und behält ihren Platz in der Sitemap.

Changelog

Changelog-Einträge (type: changelog) akzeptieren ein optionales changelog-Objekt für umfangreichere Feed- und Anzeige-Metadaten:

type: changelog
changelog:
  version: 1.2.0
  date: 2026-06-20
  category: Features

date kann hier oder auf oberster Ebene stehen — beides fließt in den Changelog-RSS-Feed ein. Die generierte Timeline-Seite und den Feed findest du unter Changelog.

Eigene Schlüssel

Jeder Schlüssel, der nicht in dieser Referenz steht, lässt den Build fehlschlagen, sodass Tippfehler früh auffallen. Projekte mit eigenen Metadaten können zusätzliche Schlüssel über frontmatter.extend in blume.config.ts freischalten. Jeder davon wird durch ein Schema validiert, das das Projekt selbst mitbringt:

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

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

---
title: Install
owner: "@sam"
reviewedAt: 2026-06-20
---

Schemas werden über die Standard Schema-Schnittstelle akzeptiert, sodass Zod (egal welche Version dein Projekt installiert hat), Valibot und ArkType alle funktionieren. Jeder deklarierte Schlüssel wird auf jeder Seite validiert, auch dort, wo er fehlt. Ein Pflichtschema erzwingt den Schlüssel also auf der gesamten Website. Markiere ihn mit .optional(), damit er nur dort validiert wird, wo er vorhanden ist. Alle anderen Schlüssel werden weiterhin strikt validiert, und eingebaute Felder kannst du nicht neu deklarieren.

Schlüssel pro Typ

Wenn du Schlüssel nur für einen bestimmten Inhaltstyp verlangen willst, etwa den status eines RFC oder die severity eines Incident-Reports, deklariere sie stattdessen unter content.types. Als Schlüssel dient dabei der Frontmatter-type, für den sie gelten:

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

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

---
title: OpenAPI request schemas
type: rfc
domain: architecture
status: enforced
---

Schlüssel pro Typ folgen denselben Validierungsregeln wie extend, gelten aber nur für Seiten, deren aufgelöster type passt. Ist die Deklaration für content.defaultType, gehören dazu auch Seiten, die gar keinen type setzen. Ein Schlüssel gehört zu genau einer Deklaration, entweder für die gesamte Website oder pro Typ, nicht zu beiden. Ein Schlüssel, der nur für einen anderen Typ deklariert ist, bleibt überall sonst unbekannt. Ein verirrter status auf einer normalen Doku-Seite lässt den Build also weiterhin fehlschlagen.

Besteht eine Seite die Validierung nicht, schlägt blume build fehl, und die Diagnose nennt Datei und Schlüssel. Mit --no-strict läuft der Build trotzdem durch, und die fehlerhaften Seiten werden aus der Ausgabe entfernt. Wie viele das sind, steht in der Build-Zusammenfassung.

Die Schemas werden aus blume/schema exportiert, damit du sie für Editor- und Migrations-Tools nutzen kannst.