Assets · Scribe

Scribe behandelt statische Assets (aktuell Bilder) als erstklassige, im Schema deklarierte Referenzen und nicht als lose Zeichenketten. Das Grundprinzip: Komponenten bauen Asset-URLs niemals durch das Verketten von Strings zusammen. Im Frontmatter wird eine kanonische Quellreferenz gespeichert. Die Runtime löst diese beim Laden in die tatsächliche Auslieferungs-URL auf. Genau diese eine Indirektion sorgt dafür, dass sich publicPath, CDNs und Content-Hashing einfach als Konfiguration einbinden lassen, ohne dass Code-Migrationen nötig sind.

Configuration

Die Konfigurationsgruppe assets legt fest, wo die Quelldateien liegen und wie sie ausgeliefert werden. Das einfache assetsDir funktioniert weiterhin als veralteter Alias für { dir: assetsDir }.

export default defineConfig({
  // ...
  assets: {
    dir: "public",            // Speicherort der Quelldateien, relativ zu rootDir. Standard: "public".
    publicPath: "/",          // URL-Präfix für die Auslieferung. Ein Pfad ("/static/") oder ein CDN-Origin. Standard: "/".
    managedDirs: ["/blog-images"], // Zusätzliche Scribe-verwaltete Webpfad-Roots, die von keinem field.asset() abgedeckt werden.
  },
});

publicPath folgt hierbei der bekannten Konvention von webpack und Vite. Einträge unter managedDirs sind Quellverzeichnisse (Source Roots). Es handelt sich um Verzeichnisse, die in MDX-Inhalten referenziert werden, aber nicht an ein spezifisches Asset-Feld gebunden sind.

`field.asset()`

import { field } from "scribe-cms";

const garmentSchema = z.object({
  title: field.translatable(z.string()),
  productImage: field.asset({
    dir: "/try-on/garments",   // Wert muss sich unter diesem Webpfad befinden
    formats: ["webp"],          // Erlaubte Dateiendungen
    maxKB: 150,                 // Dateigrößen-Budget (gibt eine Warnung aus)
    optional: false,            // Standardwert
  }),
});

Wie bei field.relation() werden Einschränkungen im Optionen-Objekt definiert und nicht über verkettete Zod-Methoden. Durch Chaining würde das Schema geklont und die Metadaten gingen verloren. Asset-Felder sind immer struktureller Natur: Asset-Pfade werden niemals an die Übersetzung übergeben.

Option	Typ	Bedeutung
`dir`	`string`	Präfix für den Webpfad, unter dem der Wert liegen muss. Deklariert zudem ein Managed Root.
`template`	`string`	Vorlage für abgeleitete Pfade, z. B. `"/try-on/garments/{slug}/product.webp"`. `{slug}` ist der englische Slug des Eintrags. Wenn gesetzt, kann das Frontmatter-Feld komplett weggelassen werden, und der Loader füllt es automatisch aus. Ein expliziter Wert überschreibt die Vorlage (ideal für das bewusste Teilen von Assets zwischen Einträgen).
`formats`	`string[]`	Erlaubte Dateiendungen (kleingeschrieben, ohne Punkt). Bei Verstößen gibt es eine Validierungswarnung.
`maxKB`	`number`	Budget für die Dateigröße. Bei Verstößen gibt es eine Validierungswarnung.
`optional`	`boolean`	Feld darf fehlen (nur sinnvoll ohne `template`). Wenn ein Wert angegeben ist, die Datei aber fehlt, führt das weiterhin zu einem Fehler.

Der Frontmatter-Wert ist ein relativer Webpfad bezogen auf assets.dir, z. B. /try-on/garments/denim-flare/product.webp. Dies entspricht der gleichen Konvention wie bei einfachen Bild-Strings. Es wird kein neues URI-Schema benötigt. Auf der Festplatte speichert das Frontmatter die Quellreferenz (oder gar nichts, falls eine Vorlage genutzt wird). Aufgelöste URLs existieren nur im Runtime-Output. Statische Exporte, Rohdaten und auch das Übersetzungssystem sehen immer nur die Quellwerte.

Loader resolution

Wenn die Runtime ein Dokument lädt, durchläuft sie das Schema auf der Suche nach Asset-Feldern und führt für jedes Feld folgende Schritte aus:

Fehlt der Frontmatter-Wert und das Feld hat ein template, wird der Pfad aus der Vorlage generiert ({slug} wird zum englischen Slug).
Das Präfix assets.publicPath wird vorangestellt (verbunden ohne doppelte Schrägstriche, absolute Ursprünge für publicPath werden unterstützt).

Konsumenten erhalten so direkt die fertigen URLs, ohne zusätzliche Aufrufe:

const garment = scribe.garment.get("denim-flare");
garment.frontmatter.productImage;
// "/try-on/garments/denim-flare/product.webp"                       (publicPath "/")
// "https://cdn.example.com/try-on/garments/denim-flare/product.webp" (CDN publicPath)

Die Auflösung erfolgt erst, nachdem strukturelle Felder mit den Lokalisierungsdokumenten zusammengeführt wurden. So erhält jede Spracheingabe die korrekt aufgelösten Werte aus der englischen Quelle.

`scribe.assets.url(ref)`

Ein Fluchtweg für Bilder im MDX-Body und Ad-hoc-Fälle. Es wendet publicPath auf eine rohe Referenz an:

scribe.assets.url("/blog-images/hero.webp"); // publicPath wird angewandt

Sie können Assets auch direkt im MDX-Body über das Inline-Token asset referenzieren. Dieses wird beim Lesen auf exakt die gleiche Weise aufgelöst.

Validation

Der Befehl scribe validate prüft deklarierte Asset-Felder:

Fehlende Datei bei einem Pflicht-Asset-Feld: Fehler (blockiert den Build, genau wie eine ins Leere laufende Pflichtrelation).
Fehlende Datei bei einem optional-Feld mit vorhandenem Wert: Ebenfalls ein Fehler. optional bedeutet lediglich, dass das Feld fehlen darf, aber nicht, dass ein angegebener Pfad auf eine nicht existierende Datei verweisen darf.
Wert außerhalb des festgelegten dir: Fehler.
Dateiendung nicht in formats: Warnung.
Datei größer als maxKB: Warnung.
Bei Feldern mit Vorlagen wird der generierte Pfad validiert. Die Datei muss existieren, auch wenn das Frontmatter den Wert weglässt.

Die Meldungen enthalten immer die Zuordnung zum jeweiligen Feld, z. B. garment/denim-flare: productImage → /try-on/garments/denim-flare/product.webp not found. Unabhängig davon werden Strings in Frontmatter und MDX-Bodies, die wie Bilder aussehen, heuristisch erfasst und bei Fehlen weiterhin als Warnungen gemeldet. Dies deckt Bilder im Body ab, ohne dass eine Migration erforderlich ist.

Studio

Das Studio zeigt Assets im reinen Lesemodus (Read-only) an:

Der Entry Inspector rendert Asset-Felder als Bildvorschau samt aufgelöster URL, Dateigröße und Abmessungen. Fehlt eine Datei, wird ein rotes Abzeichen angezeigt.
Der Asset Browser (/assets) bietet ein Thumbnail-Raster pro Managed Root. Jedes Asset wird mit Pfad, Größe, Abmessungen und einer "Referenziert von"-Liste aller darauf verweisenden Einträge und Felder dargestellt. Abzeichen markieren unreferenzierte Assets (potenzielle Waisen), fehlende aber referenzierte Dateien sowie Assets, die zu groß sind oder vom Format abweichen.
Die Gallery View ermöglicht es jedem Typ mit einem Asset-Feld, die Eintragsliste als Kartenraster darzustellen. Dies ist eine ideale QS-Wand für generierte Bilder.