Validieren

blume validate prüft jeden Link in deinen Inhalten – Seiten, Anker, Assets und optional externe URLs – und lässt CI fehlschlagen, sobald einer kaputt ist.

blume validate liest deine Inhalte so ein, wie es ein Build tut, und prüft jeden Link, den es findet. Es wird nichts generiert oder gebaut, deshalb ist es die schnelle Prüfung, die du vor blume build schalten kannst:

blume validate

Interne Seitenlinks (/guides/intro, ./sibling) müssen auf eine echte Seite verweisen – kaputte Links werden als Fehler gemeldet. Gelesen wird jede Linkform, die Markdown und MDX rendern: Inline-Links, auch solche, deren Beschriftung in die nächste Zeile umbricht; Referenz-Links, die an ihrer Definition [label]: /target geprüft werden (bei einem doppelt definierten Label an der ersten, denn die wird gerendert); Autolinks (<https://…>, in .md); und ein String-href einer Komponente (<Card href="./install">). Ein root-relativer Link auf eine Markdown-Datei in deinen Inhalten (/guides/setup.md) wird an der Seite geprüft, die diese Datei veröffentlicht, denn dorthin lässt der Build ihn zeigen. Ein solcher Link, der dort keine Datei benennt, wird als Markdown-Kopie der Seite geprüft. Das Ziel eines Links wird so gelesen, wie der Renderer es liest: [x](<https://example.com/a(b>) zeigt also auf https://example.com/a(b und ![](image\(1\).png) auf image(1).png, mit beliebigen Leerzeichen drumherum und einem Titel in einer seiner Anführungsformen ("…", '…' oder (…)) dahinter. Links in Code (in Codeblöcken, auch in einem Codeblock innerhalb eines Blockzitats, oder inline) und in Kommentaren ( in .md, {/* … */} in .mdx) werden nie gerendert und deshalb nicht geprüft. Ein kleingeschriebenes HTML-<a href> auf eine Seite wird genau so ausgeliefert, wie es geschrieben ist. Deshalb wird es so geprüft, wie ein Browser es liest: Ein relativer Pfad wird relativ zur URL der Seite aufgelöst, und es wird kein basePath hinzugefügt (ein root-relativer Pfad erhält wie jeder Link eine Deployment-base). Ein href={…}-Ausdruck wird nicht geprüft.
Anker-Links (#section, /guides/intro#setup) müssen zu einem Anker auf der Zielseite passen – der ID einer Überschrift (generiert oder festgelegt), dem id-Attribut eines rohen HTML-Elements oder einem <a name>. Treffer, die fehlen, werden als Warnungen gemeldet. IDs in Codeblöcken, Inline-Code, HTML-Kommentaren und <Prompt>-Blöcken zählen nicht.
Andere Link-Schemata (mailto:, tel:, ein vscode:-Deep-Link einer App) werden nicht geprüft: Ob der Browser der Lesenden oder eine installierte App so einen Link verarbeitet, lässt sich nicht feststellen. Die Ausnahme sind die eigenen Link-Schemata von ReadMe: doc:, ref:, page:, changelog: und blog: werden nur auf ReadMe aufgelöst und sind überall sonst tote Links, deshalb wird jedes davon als Warnung gemeldet. Verlinke die Seite stattdessen über ihren Pfad.
Asset-Links werden dort geprüft, wo die Datei liegt: ein absoluter Pfad (/logo.png) im Verzeichnis public/, ein relatives eingebettetes Bild (![](./diagram.png) oder das <Card img="./cover.png"> einer Karte) im Ordner der jeweiligen Seite. Ein relativer Link auf jede andere Datei ([spec](./spec.pdf), ein <a href> oder das href einer Komponente) wird ebenfalls im Ordner der Seite geprüft, da Blume dort eine Datei zusammen mit der Seite veröffentlicht. Ein Link, der keine Datei neben der Seite benennt, wird als Route der Website gegen public/ aufgelöst. Das src eines Medienelements (<img>, <source>, <video> oder <audio>, als rohes HTML in .md oder als Element in .mdx) wird genauso geprüft: Ein relatives src wird neben der Seite gesucht und sonst in public/, also dort, wo der Browser es anfordert. Ein Projekt ohne Ordner public/ liefert keine öffentlichen Dateien aus, daher wird ein absoluter Asset-Pfad dort als fehlend gemeldet. Ein .html-Link (./setup.html, /guides/setup.html) ist ebenfalls ein Dateilink: Blume liefert Seiten unter ihren Routen aus, nie unter .html-URLs. Wenn public/ diese Datei nicht enthält, wird der Link deshalb gemeldet – mit der Route der Seite als Lösungsvorschlag, wenn eine Seite dazu passt.
Weiterleitungsziele in redirects müssen irgendwohin führen: Ein exaktes internes to muss zu einer Seite, einer Datei oder einer anderen Weiterleitung führen. Ein to mit Muster muss zu einem Pfad führen, unter dessen literalem Anfang etwas ausgeliefert wird (/v2/ in /v2/:slug*). Ein Ziel, das nirgendwohin führt, ist eine Warnung und wird an seinem to in blume.config.ts verortet. Ein Link auf das from einer Weiterleitung ist in beiden Fällen gültig. Externe Ziele werden nicht geprüft.
Externe Links werden nur mit --external geprüft (standardmäßig deaktiviert, da dafür Netzwerkzugriff nötig ist). Ein toter Link ist ein Fehler: ein 404 oder 410 oder ein Hostname, der sich nicht auflösen lässt. Alles andere, was fehlschlägt, ist eine Warnung, da es häufiger an der anderen Website oder am Netzwerk liegt als am Link: jeder andere Fehlerstatus (ein 401 oder 403 von einer Website, die Bots abweist, ein 429-Rate-Limit, ein 5xx-Ausfall), eine abgelehnte oder abgebrochene Verbindung oder keine Antwort innerhalb von 10 Sekunden. Um URLs auszulassen, die sich von dort, wo der Befehl läuft, nicht prüfen lassen – etwa eine Platzhalter-Domain, einen lokalen Server oder eine Website, die Bots abweist –, übergib --ignore. Eine nackte URL, die GitHub-flavored Markdown von sich aus verlinkt, ohne Link-Syntax drumherum, wird nicht gelesen; blume audit --external prüft sie in der gebauten Website.

Was als Seite zählt

Links werden gegen alles aufgelöst, was die gebaute Website ausliefert, nicht nur gegen Markdown-Seiten: eigene .astro-Seiten, Seiten der API-Referenz, den generierten Changelog-Index, jede konfigurierte Weiterleitung und auf einer mehrsprachigen Website die Fallback-URL einer nicht übersetzten Seite unter jeder Locale. Die Dateien, die Blume neben deine Seiten schreibt, zählen ebenfalls, solange sie in der Konfiguration aktiviert sind: /llms.txt und /llms-full.txt, die Sitemap, /robots.txt, die RSS-Feeds, /openapi.json, /agent-readability.json, /skill.md und die .well-known-Discovery-Dateien wie /.well-known/agent-skills/index.json. Dasselbe gilt für einen Ordner in public/ mit einer index.html: Für public/demo/index.html zählen /demo und /demo/, so wie ein statischer Host den Ordner ausliefert. Eine Seite, die nicht lädt, weil ihr Front Matter ungültig ist oder sich ihr .mdx nicht parsen lässt (BLUME_MDX_SYNTAX), wird zusammen mit den Link-Ergebnissen gemeldet. Eine Seite, die nie lädt, ist nämlich ein blinder Fleck der Link-Validierung und kein sauberes Ergebnis.

Flags

--external – prüft zusätzlich externe http(s)-Links über das Netzwerk.
--ignore <glob> – fragt mit --external keinen externen Link ab, dessen URL zum Glob passt, und meldet für ihn nichts. Der Glob wird mit der vollständigen URL des Links abgeglichen, inklusive Schema: * passt innerhalb eines Pfadsegments und ** über Segmente hinweg. So überspringt --ignore "https://api.acme.example/**" jeden Link zu diesem Host und --ignore "http://localhost:*/**" jeden lokalen Server. Wiederhole das Flag für weitere Muster und setze jedes in Anführungszeichen, damit deine Shell es nicht expandiert. Interne Links werden immer geprüft: Sie werden gegen deine eigenen Seiten aufgelöst, also behebe einen kaputten Link oder füge eine Weiterleitung hinzu.
--strict – beendet sich auch bei Warnungen mit einem Exit-Code ungleich null. Hinweise der Stufe „info“ bleiben rein informativ.
--json – gibt die Diagnosen als JSON auf stdout aus statt als Terminal-Bericht.

Diagnosen

Code	Schweregrad	Bedeutung
`BLUME_BROKEN_LINK`	error	Ein interner Link zeigt auf eine Route, die von keiner Seite bereitgestellt wird. Ist es ein relativer Link auf eine vorhandene Datei, deren Name oder Ordnername mit `_` beginnt, weist der Lösungsvorschlag darauf hin: Diese Datei ist ein Partial und wird nicht veröffentlicht.
`BLUME_BROKEN_ANCHOR`	warning	Die Seite existiert, hat aber keinen Anker, der zum Fragment passt.
`BLUME_BROKEN_ASSET`	warning	Ein absoluter Pfad liegt nicht in `public/`, ein relatives eingebettetes Bild liegt nicht neben der Seite, ein `.html`-Link benennt keine Datei in `public/`, oder ein Medien-`src` benennt eine Datei, die die Website unter dieser URL nicht ausliefert.
`BLUME_BROKEN_REDIRECT`	warning	Das interne `to` einer Weiterleitung führt zu keiner Seite, keiner Datei und keiner anderen Weiterleitung.
`BLUME_UNSUPPORTED_LINK_SCHEME`	warning	Ein Link verwendet eines der Link-Schemata von ReadMe (`doc:`, `ref:`, `page:`, `changelog:`, `blog:`), denen Browser nicht folgen können.
`BLUME_DEAD_LINK`	error oder warning	Ein externer Link (mit `--external`) hat 404/410 zurückgegeben oder sein Host lässt sich nicht auflösen (error), oder er bekam einen anderen Fehlerstatus, keine Verbindung oder nicht rechtzeitig eine Antwort (warning).

Der Exit-Code ist der Vertrag: Bei Fehlern wird mit einem Wert ungleich null beendet, und --strict sorgt dafür, dass Warnungen dasselbe bewirken.

JSON-Ausgabe

Mit --json schreiben blume validate (und blume doctor) ein einzelnes Objekt auf stdout. Es enthält eine diagnostics-Liste und eine summary mit der Anzahl pro Schweregrad. Jeder Eintrag der Liste enthält seinen code, severity und message, die file relativ zum Projektstammverzeichnis, dazu line und column, wenn das Ergebnis eine Position hat, eine suggestion und eine docsUrl, die auf die Seite verweist, die den Code erklärt. Der Exit-Code bleibt unverändert. Derselbe Aufruf kann also CI absichern und gleichzeitig eine Editor-Integration speisen.