Seiten

Wie die Dateien in deinem Content-Ordner zu Seiten werden und wie du sie organisierst und benennst, damit Routing und Navigation automatisch abgeleitet werden.

Deine Dokumentation ist einfach ein Ordner voller Markdown- und MDX-Dateien. Blume macht aus jeder Datei eine Seite — Routing, Navigation und Metadaten werden aus dem Dateisystem abgeleitet, es gibt also kein Manifest, das synchron gehalten werden muss.

Inhalte liegen unter deinem Content-Root (standardmäßig docs/; änderbar über content.root in blume.config.ts).

Markdown und MDX

Blume rendert zwei Arten von Dateien:

• .md — Markdown für reinen Fließtext: GFM, Frontmatter, typografische Satzzeichen sowie Hoch- und Tiefstellung.
• .mdx — alles, was .md bietet, plus Komponenten und die nur in MDX verfügbaren Direktiven, Paketinstallationen und Mathematik.

Greif zu .md, wenn eine Seite nur aus Fließtext besteht, und zu .mdx, wenn sie Komponenten oder Direktiven braucht. Der Wechsel ist so einfach wie das Umbenennen der Datei.

In .mdx beginnt { einen JavaScript-Ausdruck und < ein JSX-Tag. Text, der in .md problemlos funktioniert, kann deshalb eine Seite kaputt machen: eine geschweifte Klammer als reiner Text, ein HTML-Kommentar (schreib {/* … */}) oder ein nicht geschlossenes Element (schreib <br />). Blume parst jede .mdx-Seite beim Einlesen des Projekts. Deshalb melden blume dev, blume validate, blume doctor und blume check eine Seite, die sich nicht parsen lässt, als BLUME_MDX_SYNTAX — einen Fehler mit der Zeile und Spalte, an der MDX abgebrochen hat. blume build bricht an dieser Stelle ab, bevor überhaupt etwas kompiliert wird. Mit --no-strict lässt der Build die Seite weg und baut den Rest der Website. blume dev behält die Seite, und wenn du sie öffnest, wird der Fehler angezeigt.

Ein Ausdruck kann sich parsen lassen und trotzdem beim Rendern der Seite fehlschlagen, etwa {user.name} auf einer Seite, auf der nichts user definiert. blume build meldet das als BLUME_MDX_UNDEFINED_NAME in der Zeile des Ausdrucks, und zwar in der Seite oder im Partial, das ihn enthält. Um geschweifte Klammern als Text anzuzeigen, maskiere jede öffnende Klammer (\{) oder setze den Text in Inline-Code. Für einen Wert, den alle Seiten teilen, definierst du eine Variable.

Dateien und Routen

Jede Datei wird anhand ihres Pfads unterhalb des Content-Roots auf eine Route abgebildet:

Verschachtelte Ordner werden zu verschachtelten Routen, und eine index.mdx in einem Ordner wird zur eigenen Seite dieses Ordners.

Zeichen, die die URL einer Seite kaputt machen würden — #, ?, % und : — werden aus ihrer Route entfernt, sodass 100%.mdx unter /100 veröffentlicht wird. Verzichte in Datei- und Ordnernamen komplett auf # und ?: Der Content-Loader von Astro kann eine solche Datei nicht lesen, daher meldet Blume sie als Fehler und lässt sie aus der Website weg. Benenne sdks/c#.mdx in sdks/c.mdx um, dann wird sie unter /sdks/c veröffentlicht — genau die Route, die nach dem Entfernen der Zeichen ohnehin entstanden wäre.

Sortierung mit numerischen Präfixen

Stelle einer Datei oder einem Ordner eine Zahl und ein -, _ oder . voran, um die Reihenfolge in der Seitenleiste zu steuern. Das Präfix wird aus der URL entfernt, sodass du Seiten neu anordnen kannst, ohne Links zu zerstören:

01-introduction.mdx  ->  /introduction
02-installation.mdx  ->  /installation

Eine Version oder ein Datum am Anfang eines Namens ist Teil des Namens und keine Sortierangabe: 1.2.0.mdx wird zu /1.2.0 und 2024-01-05-launch.mdx zu /2024-01-05-launch. Diese Formen erkennt Blume als Datum:

• Ein ISO-Datum, YYYY-MM-DD: 2024-01-05.mdx wird zu /2024-01-05.
• Zuerst Tag oder Monat, dann eine vierstellige Jahreszahl, also D-M-YYYY oder M-D-YYYY mit ein oder zwei Ziffern für Tag und Monat: 12-05-2022.mdx wird zu /12-05-2022.
• Ein Jahr und ein Monat, YYYY-MM: 2024-01.mdx wird zu /2024-01.

Ein Datum steht entweder am Ende des Namens, oder auf das Datum folgt ein -, _ oder . und danach der Rest des Namens (2024-01-recap.mdx). Frühere Blume-Versionen haben bei den letzten beiden Formen die erste Zahl als Sortierpräfix gelesen. Dadurch wurde 12-05-2022.mdx unter /05-2022 und 2024-01.mdx unter /01 veröffentlicht. Diese alten URLs leiten jetzt auf die neuen weiter, sofern dort keine andere Seite liegt. Nur Datei- und Ordnernamen verlieren ein Präfix (die Notizen eines Obsidian-Vaults zählen als Dateien). Ein slug im Frontmatter sowie eine Seite aus einer Content-Quelle wie einem CMS oder GitHub Releases behalten den Namen, den sie bekommen haben.

Die Sortierung hat mehrere Ebenen — die vollständigen Vorrangregeln findest du unter Navigation.

Gruppenordner

Setze einen Ordnernamen in Klammern, um dessen Seiten in der Seitenleiste zu gruppieren, ohne ein URL-Segment hinzuzufügen:

docs/(internal)/security.mdx  ->  /security

Die Seiten teilen sich eine Seitenleisten-Gruppe „Internal“, behalten aber flache URLs ohne Klammern. Ein Gruppenordner kann wie jeder andere Ordner ein numerisches Präfix tragen, innerhalb oder außerhalb der Klammern: (01-internal) und 01-(internal) werden beide zuerst einsortiert und wie (internal) geroutet.

Entwürfe

Markiere eine Seite als Entwurf, um sie aus Produktions-Builds herauszuhalten, sie aber weiterhin in blume dev ansehen zu können:

---
title: Work in progress
draft: true
---

blume build überspringt Entwürfe; blume dev rendert sie, damit du offen daran arbeiten kannst.

Inhaltstypen

Jede Seite hat einen Typ, festgelegt über das Frontmatter-Feld type (Standard doc). Typen ermöglichen es Blume, Gruppen von Seiten unterschiedlich zu behandeln — vor allem werden blog- und changelog-Seiten in Feeds gesammelt.

---
title: v1.2.0
type: changelog
date: 2026-06-20
changelog:
  version: 1.2.0
  category: Features
---

Der Typ ist unabhängig davon, wo die Datei liegt, aber per Konvention gehören Blogbeiträge unter blog/ und Changelog-Einträge unter changelog/. Beide erhalten automatisch einen RSS-Feed, und Changelog-Einträge werden zusätzlich in einer generierten /changelog-Timeline gesammelt. Wie du sie jeweils schreibst, erfährst du unter Blog und Changelog.

Feeds

Blume erzeugt automatisch einen RSS-Feed für jeden Inhaltstyp, der in seo.rss.types aufgeführt ist — standardmäßig blog und changelog — sofern er mindestens eine Seite enthält. Feeds werden unter /<type>/rss.xml ausgeliefert:

Gib jedem Eintrag ein date, damit die Einträge nach Aktualität sortiert werden und ein pubDate tragen. Ein YAML-Datum ohne Anführungszeichen ist in Ordnung — Blume normalisiert es:

---
title: Introducing Blume
type: blog
date: 2026-06-22
description: Why we built a markdown-first docs framework.
---

Feeds benötigen eine absolute Website-URL, setze also deployment.site. Blume fügt jeder Seite <link rel="alternate">-Tags hinzu, damit Browser und Feedreader sie automatisch finden. Wie du die jeweiligen Inhaltstypen schreibst, erfährst du unter Blog und Changelog.

Auf dieser Seite

Jede Seite erhält automatisch ein Inhaltsverzeichnis, das aus ihren Überschriften erstellt wird. Auf breiten Bildschirmen sitzt es in einer haftenden Seitenleiste neben deinem Inhalt; auf schmaleren Bildschirmen klappt es in ein Panel Auf dieser Seite oberhalb der Seite zusammen. Beim Scrollen wird der Eintrag des Abschnitts hervorgehoben, den du gerade liest, sodass du auf einer langen Seite immer weißt, wo du dich befindest.

Blume wandelt jede Überschrift in einen Anker-Slug um, sodass jeder Eintrag direkt auf seinen Abschnitt verlinkt — und du kannst auf jede Überschrift per Deeplink verweisen, indem du ihren Slug an die URL anhängst (.../my-page#getting-started).

Standardmäßig listet das Inhaltsverzeichnis deine ##- und ###-Überschriften (H2 und H3) auf; setze toc, um den Überschriftenbereich zu ändern oder das Inhaltsverzeichnis auszuschalten. Eine Seite ohne Überschriften in diesem Bereich hat schlicht kein Inhaltsverzeichnis.

Wie geht es weiter