Modello dei contenuti e contenuti multimediali
Come un sito separa i testi dal layout, su cosa si basano le verifiche dell’editor, dell’API e degli agenti e come funzionano i contenuti multimediali.
Ogni sito è un progetto Astro che conserva i contenuti modificabili dal proprietario in file tipizzati e il layout nel codice. Una pagina legge i contenuti e li dispone nel layout. Non contiene mai direttamente il nome dell’attività, un prezzo o gli orari di apertura.
Il modello dei contenuti è l’elenco dei tipi di contenuto e dei relativi campi. Viene definito una sola volta in src/content.config.ts del progetto (uno schema Zod per tipo). A ogni build viene esportato come JSON Schema; l’editor, la REST API, MCP e la CLI verificano ogni modifica in base a questo schema. Se un valore non è valido, viene rifiutato indicando il nome del campo e non viene salvato nulla.
Il modello deriva dall’ultima build. Prima di consultare il modello dei contenuti, esegui una nuova build del sito.
Raccolte e contenuti singoli
Una raccolta contiene più voci, ciascuna in un file. Il nome del file è lo slug della voce: lettere minuscole, cifre e trattini. Un contenuto singolo è un unico documento JSON in un percorso fisso.
Il modello iniziale di Atelier201 include:
| Nome | Tipo | Contenuto |
|---|---|---|
business | contenuto singolo | Nome, slogan, descrizione, telefono, email, indirizzo, orari di apertura, social, dati legali, link per prenotazioni e mappe e lingua del sito |
theme | contenuto singolo | Quattro colori del brand, raggio degli angoli, abbinamento di font e modalità chiara, scura o automatica |
navigation | contenuto singolo | Link nell’intestazione, link nel piè di pagina e pulsante di invito all’azione |
integrations | contenuto singolo | ID di Google Analytics, dominio Plausible e codice da aggiungere nell’head o alla fine del body |
services | raccolta, JSON | Servizi con nome, descrizione, prezzo, ordine e immagine |
blog | raccolta, Markdown | Articoli con titolo, descrizione, data, autore, immagine di copertina, tag, servizi correlati (relazione con services tramite slug) e indicatore di bozza |
Il modello iniziale è una struttura di base: include queste due raccolte come esempi e non impone una visione specifica dell’attività. Puoi eliminare quelle che non ti servono e aggiungere le tue, ad esempio un team, un menu o degli eventi.
Una raccolta di contenuti usa Markdown: campi nel front matter e un corpo. Una raccolta di dati usa JSON e non ha un corpo.
Se la raccolta ha un campo per le bozze, una nuova voce creata tramite API o MCP viene inizialmente salvata come bozza, così una persona può decidere se pubblicarla.
Modificare i contenuti senza compromettere il layout
Per modificare testi, voci e dati dell’attività, preferisci le chiamate ai contenuti invece di modificare direttamente i file:
| Attività | REST | MCP | CLI |
|---|---|---|---|
| Leggere il modello | Leggere il modello dei contenuti | get_content_model | atelier201 content model |
| Scrivere una voce | Creare o aggiornare una voce | save_entry | atelier201 content save |
| Modificare un testo | Modificare un campo | set_field | atelier201 content set |
Usa le chiamate ai file solo per modificare il codice: un layout, un componente o il modello dei contenuti stesso. Per aggiungere un campo, inseriscilo in src/content.config.ts con .default() o .optional(), così le voci esistenti restano valide.
Modifica in linea: data-atelier201-field
Il proprietario fa clic su un breve testo nella pagina e lo modifica direttamente. È possibile perché il testo contiene l’indirizzo del campo da cui proviene:
<h1 data-atelier201-field="business:/name">Morning Crumb Bakery</h1>
<time data-atelier201-field="business:/hours/2/close">15:00</time>L’indirizzo ha il formato <singleton>:<JSON pointer>: business, theme o
navigation, seguito da due punti e da un puntatore RFC 6901
all’interno del file del contenuto singolo. Lo stesso indirizzo funziona con set_field e
atelier201 content set.
Quando modifichi un componente, rispetta queste regole:
- Aggiungi l’attributo a un elemento il cui testo completo corrisponde esattamente al campo, senza altri contenuti al suo interno. Atelier201 sostituisce il testo dell’elemento. Per «Chiamaci: 555 0100», racchiudi in uno
spansolo il numero. - Sposta l’attributo insieme all’elemento quando ne cambi lo stile e aggiungilo ovunque mostri un campo di un contenuto singolo in una nuova posizione.
- Non aggiungerlo a testi composti da più campi, a testi trasformati (come una data formattata), ai corpi Markdown o alle voci di una raccolta. In una pagina, una voce deve invece avere
data-atelier201-entry="<collection>/<slug>"sul contenitore.
Il sito rimane statico
Un sito realizzato con Atelier201 è un sito Astro statico: niente adattatore server, rendering lato server, framework lato client o richieste ad altre origini durante l’esecuzione, inclusi font, tag di analisi e mappe incorporate. Usa una sola lingua, impostata in business.locale. Le dipendenze sono astro e @astrojs/mdx (disattivata finché non si aggiunge mdx() alla configurazione), perché la build viene eseguita senza accesso alla rete. Il file AGENTS.md del modello iniziale elenca queste regole per gli agenti che modificano il codice.
Contenuti multimediali
Carica un’immagine, un PDF o un breve video sul sito, quindi fai riferimento al file con /media/<filename> nei contenuti, ad esempio in coverImage di un articolo del blog.
- Ogni file può avere dimensioni fino a 20 MB. Tramite MCP, i caricamenti sono codificati in base64 e limitati a 5 MB.
- Aggiungi un testo
altalle immagini per chi non può vederle. - I contenuti multimediali occupano spazio nel piano: 100 MB per una bozza e 5 GB per un Site.
- Un file caricato viene incluso dalla build successiva. Eliminandolo, non sarà presente nelle build successive; le build già pubblicate ne conservano una copia finché una nuova pubblicazione non la sostituisce.