Frontmatter
Configura titoli, descrizioni, icone, override della barra laterale e metadati SEO con il blocco YAML frontmatter di ogni file MDX.
Ogni file MDX inizia con un blocco YAML racchiuso tra marcatori ---. Questi metadati controllano il titolo della pagina, l'aspetto della barra laterale e il modo in cui la pagina viene visualizzata quando viene condivisa sui social media o nei risultati di ricerca.
Frontmatter di base
Ogni pagina deve avere almeno un titolo:
---
title: Getting Started
description: Learn the basics in 5 minutes
---Campi disponibili
Obbligatori
| Campo | Tipo | Descrizione |
|---|---|---|
title | string | Titolo della pagina mostrato nella navigazione e nella scheda del browser |
Consigliati
| Campo | Tipo | Descrizione |
|---|---|---|
description | string | Breve riepilogo per SEO e risultati di ricerca (50-160 caratteri) |
Facoltativi
| Campo | Tipo | Predefinito | Descrizione |
|---|---|---|---|
icon | string | - | Icona Font Awesome mostrata accanto al titolo della pagina nella barra laterale di navigazione |
sidebarTitle | string | title | Titolo più breve per la navigazione nella barra laterale |
mode | string | - | Imposta "wide" per un layout a larghezza completa |
hideFooter | boolean | false | Nasconde il footer social in questa pagina |
rss | boolean | false | Abilita la generazione del feed RSS dai componenti Update presenti in questa pagina |
search | boolean | true | Imposta false per escludere la pagina dalla ricerca del sito, dalle risposte della chat AI e da MCP. La pagina resta nella barra laterale, nella sitemap e in llms.txt. Consulta Mantieni una pagina fuori dalla sola ricerca |
private | boolean | false | Richiede la password del sito per visualizzare questa pagina. L'impostazione su una pagina qualsiasi attiva la modalità per pagine specifiche nella build successiva. |
public | boolean | false | Esclude questa pagina dalla protezione con password o dall'autenticazione JWT quando l'intero sito è protetto. Ha la precedenza su private: true se entrambe sono impostate. |
groups | string[] | - | Con l'autenticazione JWT attiva, solo i visitatori il cui token elenca almeno uno di questi gruppi possono aprire la pagina; tutti gli altri ricevono un 404 e non la vedono nella navigazione. Massimo 32 gruppi per pagina. Ignorato nella modalità con password. Consulta Accesso basato sui gruppi. |
lastUpdatedDate | string | - | Sostituisce la data "Last updated on" di questa pagina invece di usare quella dell'ultimo commit Git. Metti il valore tra virgolette: "2026-09-01". La riga nel piè di pagina richiede metadata.timestamp in docs.json; la sitemap e i dati strutturati usano comunque la data. Consulta Data dell'ultimo aggiornamento |
Data dell'ultimo aggiornamento
Con metadata.timestamp attivo in docs.json, ogni pagina mostra la data dell'ultimo commit che ne ha modificato il file. lastUpdatedDate sostituisce quella data su una singola pagina:
---
title: Authentication
lastUpdatedDate: "2026-09-01"
---Usalo quando hai riletto una pagina e vuoi dichiararlo, oppure quando un commit di sola formattazione ha spostato la data senza cambiare nulla che un lettore noterebbe.
Metti il valore tra virgolette. Un 2026-09-01 senza virgolette viene letto come timestamp anziché come data e può mostrare un giorno di scarto. Un valore che non è una data viene ignorato e al suo posto compare la data del commit, quindi un errore di battitura non lascia mai la riga vuota.
La riga nel piè di pagina compare solo con metadata.timestamp attivo, ma lastUpdatedDate non è soltanto un'impostazione del piè di pagina: il <lastmod> della sitemap e il dateModified dei dati strutturati della pagina lo usano che il piè di pagina sia attivo o meno. Impostalo quando la data è quella che intendi, non solo quando vuoi mostrarla.
La sostituzione imposta anche dateModified nei dati strutturati della pagina, così i motori di ricerca e gli assistenti AI vedono la stessa data dei tuoi lettori.
SEO e social
Controlla come appare la pagina nei risultati di ricerca e nelle anteprime social. Imposta questi valori come chiavi flat di primo livello o all'interno di un blocco seo: annidato. Entrambi i metodi funzionano e i valori per pagina hanno la precedenza sui valori predefiniti seo.metatags di docs.json.
| Campo | Tipo | Predefinito | Descrizione |
|---|---|---|---|
keywords | string[] | - | Parole chiave di ricerca, emesse come tag <meta name="keywords"> |
canonical | string | auto | URL canonico della pagina, che sostituisce quello generato automaticamente |
noindex | boolean | false | Esclude questa pagina dai motori di ricerca e dalla sitemap |
og:* / twitter:* | string | - | Tag di anteprima social Open Graph e Twitter/X (ad esempio og:title, og:image, twitter:card) |
seo | object | - | Blocco annidato che contiene uno qualsiasi dei campi precedenti e altri tag meta personalizzati |
---
title: API Reference
description: REST endpoints and authentication
"og:image": /images/api-card.png
"twitter:card": summary_large_image
canonical: https://docs.acme.com/api-reference
---Consulta Ottimizzazione SEO per l'elenco completo dei tag supportati e degli esempi.
Dopo una build, incolla l'URL della pagina nello strumento gratuito OpenGraph Preview per vedere come vengono visualizzati questi tag su X, Facebook, LinkedIn, Slack, Discord e altri servizi.
Esempi
Pagina di documentazione standard
---
title: Authentication
description: Secure your API with OAuth 2.0 and API keys
icon: lock
---Titolo lungo con override della barra laterale
---
title: Configuring Single Sign-On with SAML 2.0
sidebarTitle: SSO Setup
description: Set up enterprise SSO for your organization
---Il titolo completo appare nella pagina, mentre il sidebarTitle più breve mantiene pulita la navigazione.
Layout ampio
---
title: API Reference
description: Complete API documentation
mode: wide
---La modalità estesa rimuove il sommario ed espande il contenuto a tutta larghezza. È utile per le pagine di riferimento delle API o per i contenuti con tabelle ampie.
Nascondere il footer
---
title: Custom Landing
description: A focused landing page experience
hideFooter: true
---Usa hideFooter per le landing page, le pagine del changelog o qualsiasi pagina in cui desideri una sezione inferiore più essenziale, senza link social.
Best practice SEO
Il titolo appare in:
- Schede del browser
- Risultati dei motori di ricerca
- Barra laterale di navigazione
- Condivisioni sui social media
Mantieni i titoli sotto i 60 caratteri. Inserisci le parole chiave importanti all'inizio.
# Good - clear and keyword-rich
title: Deploy to Production
# Avoid - vague or too long
title: How to Deploy Your Application to Production ServersLe descrizioni appaiono nei risultati di ricerca e nelle anteprime social. Punta a 50-160 caratteri che:
- Riassumano il contenuto della pagina
- Includano parole chiave pertinenti
- Invoglino gli utenti a fare clic
# Good - actionable and specific
description: Deploy your docs to production in under 2 minutes with zero configuration
# Avoid - generic or missing
description: Documentation pageLe icone aiutano gli utenti a consultare rapidamente la navigazione. Usa la stessa icona per le pagine correlate:
| Argomento | Icona suggerita |
|---|---|
| Primi passi | rocket |
| Autenticazione | lock |
| Riferimento API | code |
| Impostazioni | gear |
| Fatturazione | credit-card |
Consulta le icone su Font Awesome.
Convalida
Jamdesk convalida il frontmatter durante la build. Errori comuni:
Error: Page "api/auth.mdx" is missing required field: titleCorrezione: aggiungi il campo title al frontmatter.
Error: Invalid frontmatter in "guide.mdx": unexpected tokenCorrezione: controlla:
- Virgolette mancanti attorno alle stringhe con caratteri speciali
- Rientro non corretto
- Due punti mancanti dopo le chiavi
Incolla il blocco tra i marcatori --- nel validatore YAML gratuito per individuare riga e colonna dell'errore.