File seed

Un file seed descrive il modello iniziale e i dati di esempio facoltativi di un sito EmDash. I template attuali lo salvano in seed/seed.json e vi puntano con package.json#emdash.seed.

EmDash incorpora il seed in fase di build. È pensato per la prima configurazione e per comandi seed espliciti, non come una migrazione che viene eseguita a ogni deploy.

Individuazione del file

L’integrazione Astro cerca un seed in quest’ordine:

1. .emdash/seed.json.
2. Il percorso in package.json#emdash.seed.
3. seed/seed.json.
4. Il seed predefinito integrato quando non esiste alcun seed dell’utente.

Il seguente campo del pacchetto seleziona il percorso convenzionale del template:

{
  "emdash": {
    "seed": "seed/seed.json"
  }
}

Forma radice

L’esempio seguente contiene ogni proprietà radice:

{
  "$schema": "https://emdashcms.com/seed.schema.json",
  "version": "1",
  "defaultLocale": "en",
  "meta": {
    "name": "Publication",
    "description": "A publication seed",
    "author": "Example Studio"
  },
  "settings": {},
  "blockTypes": [],
  "collections": [],
  "relations": [],
  "taxonomies": [],
  "bylines": [],
  "content": {},
  "menus": [],
  "redirects": [],
  "widgetAreas": [],
  "sections": []
}

defaultLocale deve essere una stringa non vuota, senza spazi iniziali o finali.

Impostazioni

settings è un oggetto di impostazioni parziali del sito. Le proprietà comuni sono title, tagline, logo, favicon, url, postsPerPage, dateFormat, timezone, social e seo.

La procedura guidata di configurazione permette all’amministratore di sostituire il titolo e il sottotitolo inseriti dal seed. Il valore predefinito onConflict: "skip" conserva quei valori quando il seed viene applicato di nuovo e completa le impostazioni fornite che mancano ancora.

{
  "version": "1",
  "settings": {
    "title": "Field Notes",
    "tagline": "Reports from the team",
    "postsPerPage": 12,
    "dateFormat": "MMMM d, yyyy",
    "timezone": "Europe/London"
  }
}

Tipi di blocco

blockTypes definisce le forme versionate usate dai campi di collection blocks. EmDash applica queste definizioni prima delle collection, quindi un campo può nominarle in validation.allowedTypes.

Il seed seguente mantiene la versione 1 per i contenuti e le revisioni salvati, rendendo attiva la versione 2 per i nuovi blocchi:

{
  "version": "1",
  "blockTypes": [
    {
      "slug": "hero",
      "label": "Hero",
      "category": "Layout",
      "currentVersion": 2,
      "versions": [
        {
          "version": 1,
          "fields": [
            { "slug": "heading", "label": "Heading", "type": "string", "required": true }
          ]
        },
        {
          "version": 2,
          "fields": [
            { "slug": "title", "label": "Title", "type": "string", "required": true },
            { "slug": "image", "label": "Image", "type": "image" }
          ]
        }
      ]
    }
  ],
  "collections": [
    {
      "slug": "pages",
      "label": "Pages",
      "fields": [
        {
          "slug": "layout",
          "label": "Layout",
          "type": "blocks",
          "validation": { "allowedTypes": ["hero"], "maxItems": 20 }
        }
      ]
    }
  ]
}

I numeri di versione sono interi positivi contigui che partono da 1. currentVersion deve nominare una versione dichiarata. Esportare e riapplicare un seed conserva i numeri di versione esatti e il puntatore alla versione attiva; EmDash non li rinumera.

Con onConflict: "update", un seed può modificare una versione salvata solo quando la nuova definizione è compatibile. Riutilizzare un numero esistente per una definizione incompatibile fallisce con BLOCK_TYPE_VERSION_CONFLICT. Aggiungi un nuovo numero di versione per una definizione che rompe la compatibilità.

I valori di blocco salvati includono _type, _version e _key. Fornisci queste proprietà quando il contenuto del seed punta a una versione conservata. Il runtime assegna la versione attiva e una chiave quando un blocco appena scritto le omette.

Collections

Una collection richiede slug, label e fields:

{
  "version": "1",
  "collections": [
    {
      "slug": "posts",
      "label": "Posts",
      "labelSingular": "Post",
      "description": "Published articles",
      "supports": ["drafts", "revisions", "scheduling", "search", "seo"],
      "urlPattern": "/posts/{slug}",
      "routable": true,
      "commentsEnabled": true,
      "editLocking": true,
      "titleField": "title",
      "dateField": "event_date",
      "admin": {
        "listColumns": ["event_date"]
      },
      "fields": [
        { "slug": "title", "label": "Title", "type": "string", "required": true },
        { "slug": "event_date", "label": "Event date", "type": "datetime", "indexed": true },
        { "slug": "content", "label": "Content", "type": "portableText" }
      ]
    }
  ]
}

Proprietà della collection

sortOrder appartiene alla collection e controlla l’ordine della barra laterale. SeedField non ha la proprietà sortOrder. I campi vengono creati nell’ordine del loro array.

Proprietà del campo

I tipi di campo supportati sono:

• string, text, url e slug.
• number, integer e boolean.
• datetime.
• select e multiSelect.
• portableText, json e repeater.
• blocks.
• image, file e reference.

Un campo reference non salva nulla nella tabella della collection. I suoi link risiedono nella relazione a cui è collegato; vedi Relazioni.

Solo string, url, number, integer, boolean, datetime, select, reference e slug possono impostare indexed: true. Su un campo reference il flag si applica solo finché il campo non ha una relazione, perché un campo collegato non ha una colonna da indicizzare.

Validazione del campo

Lo schema di collection generato riconosce queste regole dove il tipo di campo le supporta:

retiredTypes su un campo blocks è gestito dal server. Rimuovere uno slug da allowedTypes lo ritira: i blocchi salvati esistenti restano validi, ma i nuovi blocchi non possono usarlo.

validateSeed() non verifica in profondità il tipo di ogni regola in validation o options. Una regola non valida può quindi superare la validazione del seed e fallire più tardi, quando viene costruito lo schema della collection o viene scritto del contenuto.

Relazioni

Una relazione unisce due collection e possiede i link tra le loro voci. Un campo reference si collega a una di esse e vede i suoi link da un’estremità. Il seed seguente dichiara una relazione tra posts e authors che consente un autore per articolo:

{
	"relations": [
		{
			"slug": "post_authors",
			"parentCollection": "posts",
			"childCollection": "authors",
			"parentLabel": "Posts",
			"parentLabelSingular": "Post",
			"childLabel": "Authors",
			"childLabelSingular": "Author",
			"maxChildrenPerParent": 1
		}
	]
}

Un campo reference in collections nomina la relazione a cui si collega:

{
	"slug": "author",
	"label": "Author",
	"type": "reference",
	"validation": { "relation": "post_authors" }
}

Un campo può invece nominare una targetCollection e far creare una relazione per sé, che è il percorso più breve per un link che vede una sola collection. Dichiara la relazione in relations quando entrambe le collection devono vederla, oppure per impostarne etichette e limiti. reference documenta entrambe le forme e le chiavi di validazione che ciascuna accetta.

Le due collection di una relazione sono fisse una volta che essa esiste: un seed che ne nomina altre fallisce, invece di lasciare che i link che contiene puntino a una collection che non ne è più un’estremità. Le etichette e i limiti vengono aggiornati quando il seed è applicato con onConflict: "update".

Tassonomie

Le definizioni di tassonomia identificano le loro collection di destinazione. I termini sono dati di esempio e vengono applicati solo quando includeContent è true.

{
  "version": "1",
  "taxonomies": [
    {
      "name": "category",
      "label": "Categories",
      "labelSingular": "Category",
      "hierarchical": true,
      "collections": ["posts"],
      "terms": [
        { "slug": "engineering", "label": "Engineering" },
        { "slug": "platform", "label": "Platform", "parent": "engineering" }
      ]
    }
  ]
}

Una tassonomia può avere un id locale al seed, locale e translationOf. Anche i termini possono avere queste proprietà. translationOf fa riferimento a un altro ID locale al seed. Un termine deve essere ordinato dopo il termine che traduce. Le voci di tassonomia con lo stesso name possono comparire in qualsiasi ordine, perché la voce che dichiara la struttura della tassonomia viene applicata prima delle sue traduzioni.

hierarchical e collections sono condivisi da tutti i locale di una tassonomia, quindi una voce di tassonomia il cui translationOf punta a una voce con lo stesso name può ometterli. Il motore di applicazione segue translationOf attraverso le voci con lo stesso name e li prende dall’ultima. La validazione avvisa quando una traduzione dichiara valori diversi da quelli che prende, o quando due voci che li dichiarano per una stessa tassonomia non concordano. Una tassonomia esistente mantiene i propri valori, a meno che una voce senza translationOf non li sostituisca. Questo avviene con onConflict: "update", e in ogni modalità quando il locale della voce ha la definizione integrata category o tag non modificata descritta in Comportamento di conflitto, oppure quando quella definizione integrata è l’unica della tassonomia. L’esportazione li scrive solo sulla voce a cui puntano le traduzioni.

Il parent di un termine è lo slug del termine genitore nello stesso locale. Un genitore su una tassonomia non gerarchica produce un avviso e viene ignorato. Un termine con translationOf e senza parent prende il genitore del termine che traduce.

Bylines

I bylines radice definiscono crediti di presentazione. Sono dati di esempio e richiedono includeContent: true.

{
  "version": "1",
  "bylines": [
    {
      "id": "byline-editor",
      "slug": "alex-editor",
      "displayName": "Alex Editor",
      "isGuest": true
    }
  ]
}

L’id è locale al seed ed è usato dai crediti dei contenuti. Le proprietà facoltative sono bio, websiteUrl, isGuest e avatar.

L’avatar di un byline punta a un file che esiste già nello storage configurato:

{
  "id": "byline-editor",
  "slug": "alex-editor",
  "displayName": "Alex Editor",
  "avatar": {
    "storageKey": "avatars/alex.jpg",
    "filename": "alex.jpg",
    "mimeType": "image/jpeg",
    "alt": "Alex Editor",
    "width": 400,
    "height": 400
  }
}

Il seeding dell’avatar di un byline crea o riutilizza una riga media per la chiave di storage. Non carica né scarica il file.

Contenuto

content raggruppa le voci per slug della collection. Ogni voce richiede un id locale al seed e un oggetto data. Le collection routable richiedono anche uno slug non vuoto.

{
  "version": "1",
  "content": {
    "posts": [
      {
        "id": "post-welcome",
        "slug": "welcome",
        "status": "published",
        "data": {
          "title": "Welcome",
          "content": []
        },
        "taxonomies": {
          "category": ["engineering"]
        },
        "bylines": [
          { "byline": "byline-editor", "roleLabel": "Editor" }
        ]
      }
    ]
  }
}

Per una voce routable, l’id locale al seed non è la sua identità nel database. EmDash crea un ID di database e registra la corrispondenza per i riferimenti successivi. Per una voce senza slug in una collection con routable: false, EmDash usa l’id del seed come ID salvato, così la riapplicazione resta idempotente.

In lettura, entry.id è l’identificatore di route di Astro e normalmente è lo slug. L’ID salvato nel database è entry.data.id.

Riferimenti di contenuto

Usa una stringa $ref: dentro data per sostituire un ID di contenuto locale al seed con l’ID di database creato:

{
  "id": "event-opening",
  "slug": "opening-night",
  "data": {
    "title": "Opening night",
    "venue": "$ref:venue-main-hall"
  }
}

Le destinazioni dei riferimenti devono comparire abbastanza presto da essere presenti nella mappa degli ID del motore di applicazione. Un valore $ref: non risolto resta come stringa letterale originale; validateSeed() non lo rifiuta.

Per un campo reference, dichiara i link dall’estremità genitore della sua relazione. Entrambe le estremità vedono un solo insieme di link, quindi un campo sulla collection figlia ripeterebbe link che il genitore porta già.

Riferimenti media

Usa $media nei dati di contenuto per scaricare un URL, caricarlo con l’adattatore di storage fornito, creare una riga media e sostituire l’oggetto con un valore di campo media:

{
  "featured_image": {
    "$media": {
      "url": "https://example.com/images/launch.jpg",
      "filename": "launch.jpg",
      "alt": "A product launch on stage",
      "caption": "Launch event"
    }
  }
}

In un blocco Portable Text image o in un’immagine di gallery, $media in asset diventa un riferimento media (_type: "reference", _ref, url, provider), e il testo alternativo e le dimensioni del media riempiono i propri alt, width e height dell’immagine quando mancano.

All’interno di una stessa chiamata di applicazione, i riferimenti ripetuti allo stesso URL riutilizzano il valore media già risolto. I riferimenti media del seed non accettano una proprietà locale file. mediaBasePath resta nel tipo pubblico SeedApplyOptions, ma il motore di applicazione attuale non la legge.

Quando non viene fornito alcun adattatore di storage, i riferimenti $media vengono saltati e si risolvono in null. Con skipMediaDownload: true diventano valori media esterni e non è richiesto alcun adattatore di storage.

Menu

I menu sono dati strutturali e vengono applicati anche quando includeContent è false:

{
  "version": "1",
  "menus": [
    {
      "name": "primary",
      "label": "Primary navigation",
      "items": [
        {
          "type": "page",
          "label": "About",
          "ref": "page-about",
          "collection": "pages"
        },
        {
          "type": "custom",
          "label": "Contact",
          "url": "/contact",
          "target": "_self"
        }
      ]
    }
  ]
}

I tipi di elemento consentiti sono custom, page, post, taxonomy e collection. custom richiede url; page e post richiedono ref. Gli elementi possono includere id, translationOf, label, collection, titleAttr, cssClasses, locale, target e children annidati.

Per page e post, ref nomina un ID di contenuto del seed. Una destinazione mancante produce un avviso di validazione e un elemento di menu senza riferimento di contenuto risolto. Gli elementi di menu esistenti vengono eliminati e ricreati ogni volta che quel menu viene applicato, indipendentemente da onConflict.

Reindirizzamenti

I reindirizzamenti richiedono percorsi di origine e di destinazione locali:

{
  "version": "1",
  "redirects": [
    {
      "source": "/old-path",
      "destination": "/new-path",
      "type": 308,
      "enabled": true,
      "groupName": "WordPress migration"
    }
  ]
}

Entrambi i percorsi devono iniziare con un solo /. Gli URL relativi al protocollo, i segmenti di path traversal e le nuove righe vengono rifiutati. I codici di stato consentiti sono 301, 302, 307 e 308.

Aree widget

Un’area widget contiene widget content, menu o component:

{
  "version": "1",
  "widgetAreas": [
    {
      "name": "sidebar",
      "label": "Sidebar",
      "widgets": [
        {
          "type": "menu",
          "title": "Explore",
          "menuName": "primary"
        },
        {
          "type": "component",
          "title": "Recent posts",
          "componentId": "core:recent-posts",
          "props": { "count": 5 }
        }
      ]
    }
  ]
}

Un widget content salva Portable Text in content. Un widget menu richiede menuName. Un widget component richiede componentId e può passare props. SeedWidget non ha la proprietà settings.

I widget esistenti in un’area vengono eliminati e ricreati ogni volta che l’area viene applicata, indipendentemente da onConflict.

Sections

Le section contengono contenuto Portable Text riutilizzabile:

{
  "version": "1",
  "sections": [
    {
      "slug": "newsletter-signup",
      "title": "Newsletter signup",
      "description": "Signup call to action",
      "keywords": ["newsletter", "email"],
      "source": "theme",
      "content": []
    }
  ]
}

Gli slug delle section contengono lettere minuscole, cifre e trattini. source è theme, user o import; un seed lo imposta di default su theme. Le section del tema non possono essere eliminate nell’amministrazione. Le section sono strutturali e vengono applicate anche quando includeContent è false.

Localizzazione

defaultLocale riempie i locale mancanti per tassonomie, termini, menu, elementi di menu e contenuto. La configurazione i18n attiva a runtime ha la precedenza quando presente.

Le tassonomie, i termini, i menu, gli elementi di menu e i contenuti localizzati usano i campi id e translationOf locali al seed. Metti l’elemento sorgente prima di una traduzione, così il motore di applicazione può risolverne il gruppo di traduzione. Una voce di contenuto tradotta deve impostare locale, e il suo translationOf deve nominare un’altra voce della stessa collection.

Applicare un seed in modo programmatico

applySeed() e validateSeed() sono esportati da emdash/seed. L’helper seguente valida prima di applicare:

import {
  applySeed,
  validateSeed,
  type SeedApplyOptions,
  type SeedFile,
} from "emdash/seed";

type SeedDatabase = Parameters<typeof applySeed>[0];

export async function applyProjectSeed(
  db: SeedDatabase,
  seed: SeedFile,
  options: SeedApplyOptions,
) {
  const validation = validateSeed(seed);
  if (!validation.valid) {
    throw new Error(validation.errors.join("\n"));
  }

  return applySeed(db, seed, options);
}

SeedApplyOptions

L’applicazione programmatica imposta includeContent di default su false. La procedura guidata di configurazione passa la scelta dell’amministratore sul contenuto di esempio. La CLI emdash seed include il contenuto di default, a meno che non sia impostato --no-content.

Comportamento di conflitto

onConflict non è una policy transazionale per l’intero seed:

• Collection, campi, bylines, contenuto, reindirizzamenti e section supportano i comportamenti skip, update ed error.
• Le definizioni di tassonomia e i termini rispettano la modalità di conflitto applicabile. L’eccezione sono le definizioni integrate category e tag con cui inizia ogni nuovo database: finché un sito non le modifica, un seed che le dichiara le sostituisce in ogni modalità.
• Le impostazioni usano una gestione dei conflitti per chiave. skip crea le impostazioni mancanti e conserva i valori esistenti. update sovrascrive ogni impostazione fornita; per seo e social vengono sovrascritti solo i campi forniti. error si ferma alla prima impostazione esistente; le impostazioni create prima nell’ordine del seed restano applicate.
• I menu esistenti conservano la propria riga di menu ma sostituiscono tutti gli elementi.
• Le aree widget esistenti conservano la propria riga di area ma sostituiscono tutti i widget.
• Un conflitto di contenuto viene abbinato per collection, slug e locale. Una voce senza slug in una collection non routable viene abbinata tramite il suo ID del seed.

Con onConflict: "update", i dati di contenuto vengono sostituiti e le sue assegnazioni di byline e tassonomia vengono riconciliate con il seed. Prova la modalità update su una copia prima di usarla su un sito esistente.

applySeed() restituisce contatori per collection, campi, tassonomie, bylines, menu, reindirizzamenti, aree widget, section, impostazioni, contenuto e media.

Comportamento di validazione

validateSeed() restituisce { valid, errors, warnings }. applySeed() lo chiama e lancia Invalid seed file quando sono presenti errori.

Il validatore controlla le regole strutturali richieste dal motore di applicazione, tra cui:

• Versione e defaultLocale non vuoto.
• Forme dei contenitori di collection, campo, tassonomia, termine, menu, area widget, section, byline e contenuto.
• Nomi, etichette, ID, slug richiesti e tipi di campo o widget supportati.
• Identificatori duplicati nel loro ambito pertinente.
• Tipi di campo indicizzabili e riferimenti admin.listColumns.
• Genitori di tassonomia, traduzioni di contenuto, riferimenti di byline nel contenuto e requisiti degli elementi di menu.
• Percorsi di reindirizzamento locali sicuri e codici di stato.

Alcune condizioni sono avvisi anziché errori. Esempi: una tassonomia senza collection, un genitore su una tassonomia piatta o un riferimento di contenuto di menu assente dal seed.

Il validatore non dimostra che tutti i valori data siano conformi ai campi della loro collection. Non valida inoltre in profondità le impostazioni del sito, la validation del campo, le options del campo, blocchi Portable Text arbitrari, le props dei widget component, le destinazioni $ref: nei dati di contenuto o la disponibilità remota di $media. Un seed valido può comunque fallire durante la creazione dello schema, la validazione del contenuto, il download di rete o il caricamento nello storage.

Usa l’URL $schema per l’assistenza dell’editor ed esegui il validatore eseguibile prima di applicare:

npx emdash seed seed/seed.json --validate

Comandi CLI

Applica un seed a un database SQLite locale con un comportamento di conflitto esplicito:

npx emdash seed seed/seed.json --database ./data.db --on-conflict skip

Esporta di nuovo il modello locale attuale e tutto il contenuto nel percorso del template:

npx emdash export-seed --database ./data.db --with-content=all > seed/seed.json

export-seed funziona direttamente su un file SQLite locale. Per un database D1 distribuito, esportalo prima in un file locale. Controlla le impostazioni, il contenuto e i riferimenti media esportati prima di fare il commit del risultato. Per rendere importabili su un altro sito i media esportati, passa --media-base-url; vedi URL dei media.

Passi successivi

• Creare un tema per usare un seed in un template Astro riutilizzabile.
• Evoluzione dello schema per aggiornare il modello di un sito già distribuito.
• Riferimento della CLI per le opzioni di database ed esportazione.