YAML front matter: i metadati in cima a un file Markdown
YAML front matter
YAML front matter in Markdown: sintassi, campi ed esempi | We.Inc
Cos'è il front matter YAML, le regole del ---, i campi che leggono Jekyll, Hugo, Eleventy e Astro, e uno strumento che mostra separatamente i metadati e il corpo del tuo file.
Il front matter è un blocco YAML all'inizio di un file Markdown, aperto e chiuso da una riga di tre trattini (---). I generatori di siti statici lo leggono come i dati della pagina, ad esempio titolo, data, layout e tag, poi renderizzano tutto ciò che sta sotto la riga di chiusura come contenuto della pagina.
Il supporto al front matter in quattro generatori di siti statici popolari
Generatore
Formati
Campi che legge da sé
Jekyll
YAML tra ---
layout, permalink, published; nei post: date, category, categories, tags
YAML per impostazione predefinita, più ---json e ---js
permalink, layout, tags
Astro
YAML o TOML
layout (per le pagine Markdown in src/pages)
Il front matter trasforma un semplice file Markdown in una pagina con metadati, e basta un trattino fuori posto per romperlo. Incolla un file nello strumento per vedere esattamente dove finiscono i metadati e inizia il contenuto, e quali campi di primo livello ha trovato, prima che la build si lamenti.
Incolla un file Markdown, oppure modifica il post di esempio.
Lo strumento verifica che la primissima riga sia --- (YAML) o +++ (TOML) e cerca la riga di chiusura corrispondente.
Mostra il blocco di front matter, i semplici campi di primo livello trovati e il corpo che verrà renderizzato.
Se il blocco non viene mai chiuso te lo segnala, ed è la causa più comune di una pagina che mostra i metadati come testo.
Nulla può precedere il --- di apertura, nemmeno una riga vuota o un byte order mark, altrimenti la maggior parte dei generatori tratta il blocco come testo normale.
Metti tra virgolette i titoli che contengono due punti seguiti da uno spazio, come "Prezzi: cosa è cambiato", altrimenti YAML li legge come una mappa annidata.
Scrivi le date come YYYY-MM-DD così generatori e librerie YAML concordano sul loro significato.
Tieni i campi personalizzati in un unico posto coerente. Hugo, ad esempio, ha una chiave params pensata per i tuoi valori.
Domande frequenti
Cos'è il front matter in Markdown?
Sono metadati scritti all'inizio di un file Markdown tra due righe delimitatrici. Markdown di per sé non lo definisce; generatori di siti statici e strumenti per contenuti hanno adottato questa convenzione e lo leggono come dati prima di renderizzare il resto.
Il front matter deve essere per forza YAML?
YAML è la scelta predefinita più comune, ma non l'unica. Hugo accetta TOML tra righe +++ e JSON tra parentesi graffe, Eleventy supporta ---json e ---js, e anche Astro accetta TOML.
Perché la mia pagina mostra il front matter come testo?
Di solito c'è qualcosa prima del primo ---, manca il --- di chiusura, oppure la riga di apertura ha caratteri in più. Lo strumento qui sopra segnala subito gli ultimi due casi.
Il front matter può essere vuoto?
Sì. In Jekyll una coppia vuota di righe --- segnala comunque il file per l'elaborazione, ed è così che i file CSS o i feed ottengono il rendering dei tag Liquid senza alcun metadato.
Come leggo il front matter nel mio codice?
Dividi il file ai delimitatori, interpreta la prima parte con una libreria YAML e passa il resto al tuo renderer Markdown. Eleventy lo fa con il pacchetto gray-matter, che puoi usare direttamente anche in Node.
Le regole dei delimitatori
La documentazione di Jekyll lo dice chiaramente: il front matter deve essere la prima cosa nel file e deve essere YAML valido racchiuso tra righe di tre trattini. Gli altri generatori seguono la stessa forma.
Dentro il blocco valgono le normali regole YAML. Indenta con gli spazi, metti tra virgolette i valori con caratteri speciali e usa liste per tag e categorie.
Campi da impostare su ogni pagina
Un titolo e una descrizione coprono l'intestazione della pagina e lo snippet nei risultati di ricerca nella maggior parte dei temi. Una data ordina i post, e draft o published decide se la pagina viene generata o no.
Tutto il resto dipende dai tuoi template. Ogni campo che aggiungi diventa un dato che il layout può mostrare, come il nome dell'autore, il percorso di un'immagine hero o un tempo di lettura.
Esempi di front matter
Un post del blog (YAML)
Un post tipico: titolo tra virgolette perché contiene i due punti, una data, una lista di tag e un campo personalizzato per l'autore.
Lo stesso post con front matter TOML (Hugo)
Hugo legge +++ come front matter TOML. I valori personalizzati stanno sotto la chiave params.
Separatore di front matter
Incolla un file Markdown. Lo strumento trova il blocco di front matter, elenca i suoi semplici campi di primo livello e mostra il corpo che verrà renderizzato.
File Markdown
Front matter ({f})
Campi di primo livello trovati
Nessuna semplice riga key: value al primo livello.
Corpo
Nessun front matter: la prima riga non è --- né +++, quindi l'intero file è trattato come contenuto.
Il blocco aperto con {d} non viene mai chiuso. Aggiungi una riga {d} corrispondente dopo l'ultimo campo.