Asset

Scribe gestisce gli asset statici (attualmente le immagini) come riferimenti di prima classe dichiarati nello schema, anziché come semplici stringhe libere. Il principio fondamentale è che i componenti non costruiscono mai gli URL degli asset concatenando stringhe. Il frontmatter archivia un riferimento di origine canonico, mentre il runtime lo risolve nell'URL servito durante il caricamento. Questa singola indirezione permette di introdurre publicPath, CDN e content hashing tramite una semplice configurazione, evitando migrazioni del codice. रूम Configuration Il gruppo di configurazione assets dichiara dove risiedono i file di origine e come vengono serviti. L'opzione semplice assetsDir funziona ancora come alias deprecato per { dir: assetsDir }. ts export default defineConfig({ // ... assets: { dir: "public", // where source files live on disk, relative to rootDir. Default "public". publicPath: "/", // URL prefix they are served under. A path ("/static/") or a CDN origin. Default "/". managedDirs: ["/blog-images"], // extra Scribe-owned web-path roots not covered by any field.asset() }, }); publicPath segue la convenzione di webpack e Vite per questo concetto. Le voci in managedDirs sono directory radice di origine, ovvero cartelle referenziate nei corpi MDX che non sono legate a uno specifico campo asset. रूम field.asset() ts import { field } from "scribe-cms"; const garmentSchema = z.object({ title: field.translatable(z.string()), productImage: field.asset({ dir: "/try-on/garments", // value must live under this web path formats: ["webp"], // extension allowlist maxKB: 150, // size budget (warning) optional: false, // default }), }); Come per field.relation(), i vincoli si trovano nell'oggetto delle opzioni e non in metodi Zod concatenati. La concatenazione clona lo schema e perde i metadati. I campi asset sono sempre strutturali, perciò i percorsi non vengono mai inviati al traduttore. | Opzione | Tipo | Significato | | --- | --- | --- | | dir | string | Prefisso del percorso web sotto cui deve trovarsi il valore. Dichiara anche una radice gestita. | | template | string | Modello di percorso derivato, ad esempio "/try-on/garments/{slug}/product.webp". {slug} è lo slug inglese della voce. Quando è impostato, il campo nel frontmatter può essere omesso del tutto e il loader lo compila automaticamente. Un valore esplicito sovrascrive il modello (utile per la condivisione intenzionale tra più voci). | | formats | string[] | Estensioni consentite (in minuscolo e senza punto). La violazione genera un avviso di convalida. | | maxKB | number | Limite di dimensione del file. La violazione genera un avviso di convalida. | | optional | boolean | Il campo può essere assente (ha senso solo senza template). Se il valore è presente ma il file manca, si verifica comunque un errore. | Il valore nel frontmatter è un percorso web relativo alla radice all'interno di assets.dir, come ad esempio /try-on/garments/denim-flare/product.webp. Segue la stessa convenzione di una normale stringa per un'immagine e non usa nuovi schemi URI. Su disco, il frontmatter archivia il riferimento di origine (o nulla, se usa un modello). Gli URL risolti esistono solo nell'output a runtime. Le esportazioni statiche o grezze e il traduttore vedono sempre e solo i valori di origine. रूम Loader resolution Quando il runtime carica un documento, analizza lo schema alla ricerca di campi asset e per ciascuno di essi: 1. Se il valore nel frontmatter è assente e il campo ha un template, materializza il percorso basandosi su di esso ({slug} diventa lo slug inglese). 2. Aggiunge il prefisso assets.publicPath (unito senza doppie barre. È supportato un publicPath con origine assoluta). In questo modo, chi consuma i dati ottiene gli URL finali senza dover effettuare chiamate aggiuntive: ts 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) La risoluzione avviene dopo che i campi strutturali sono stati uniti ai documenti localizzati. Questo garantisce che ogni lingua riceva i valori risolti dall'origine inglese. रूम scribe.assets.url(ref) Una soluzione di emergenza per le immagini nel corpo MDX e per i casi ad hoc. Applica publicPath a un riferimento grezzo: ts scribe.assets.url("/blog-images/hero.webp"); // publicPath applied Puoi anche fare riferimento agli asset direttamente nei corpi MDX usando il token inline asset, che viene risolto nello stesso modo in fase di lettura. रूम Validation scribe validate controlla i campi asset dichiarati: - File mancante per un campo asset obbligatorio: restituisce un errore e blocca la build (proprio come una relazione obbligatoria interrotta). - File mancante per un campo optional con un valore presente: restituisce comunque un errore. optional significa solo che il campo può essere omesso, non che un percorso dichiarato possa essere falso. - Valore esterno alla dir del campo: errore. - Estensione non inclusa in formats: avviso. - File più grande di maxKB: avviso. - I campi basati su modello convalidano il percorso materializzato. Il file deve esistere anche se il frontmatter omette il valore. I messaggi indicano l'attribuzione del campo, ad esempio garment/denim-flare: productImage → /try-on/garments/denim-flare/product.webp not found. Separatamente, le stringhe con l'aspetto di un'immagine raccolte in modo euristico dal frontmatter e dai corpi MDX vengono comunque segnalate come avvisi se mancanti. Questo garantisce la copertura delle immagini nei contenuti senza richiedere alcuna migrazione. रूम Studio Lo studio mostra gli asset in sola lettura: - L'inspector delle voci esegue il rendering dei campi asset come anteprime dell'immagine con l'URL risolto, le dimensioni del file e la risoluzione. Un file mancante viene segnalato da un badge rosso. - Il browser degli asset (/assets) mostra una griglia di miniature per ogni radice gestita. Ogni asset è accompagnato dal relativo percorso, dimensione, risoluzione e un elenco "referenziato da" per ogni voce e campo che punta ad esso. Appositi badge segnalano gli asset non referenziati (potenziali orfani), mancanti ma referenziati, troppo pesanti e con formati non conformi. - La visualizzazione galleria permette a qualsiasi tipo dotato di un campo asset di mostrare il proprio elenco di voci come una griglia di schede, offrendo uno strumento di controllo qualità visivo per le immagini generate.