Frontmatter
Configura titoli, descrizioni, icone, impostazioni della barra laterale e metadati SEO con il blocco YAML frontmatter in 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 richiede 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 navigazione della barra laterale |
sidebarTitle | string | title | Titolo più breve per la navigazione della 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 in questa pagina |
search | boolean | true | Imposta su false per escludere la pagina dalla ricerca del sito, dalle risposte della chat AI e da MCP. La pagina rimane nella barra laterale, nella sitemap e in llms.txt. Consulta Escludere una pagina solo dalla 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 alla build successiva. |
public | boolean | false | Esclude questa pagina dalla protezione tramite password (usato quando l'intero sito è protetto tramite auth.password.enabled). Ha la precedenza su private: true se entrambi sono impostati. |
SEO e social
Controlla il modo in cui la pagina viene visualizzata nei risultati di ricerca e nelle anteprime social. Puoi impostare questi valori come chiavi di primo livello o all'interno di un blocco seo: nidificato. Entrambe le modalità funzionano e i valori specifici della pagina sostituiscono le impostazioni predefinite 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 per le anteprime social di Open Graph e Twitter/X (ad esempio og:title, og:image, twitter:card) |
seo | object | - | Blocco nidificato contenente tutti i campi precedenti e qualsiasi tag meta personalizzato |
---
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 ordinata la navigazione.
Layout ampio
---
title: API Reference
description: Complete API documentation
mode: wide
---La modalità ampia rimuove il sommario ed espande il contenuto a larghezza completa. È 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 pagine di destinazione, le pagine del changelog o qualsiasi pagina in cui desideri una sezione inferiore più essenziale, senza link social.
Best practice SEO
Il titolo viene visualizzato 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 vengono visualizzate 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 individuare rapidamente gli elementi nella navigazione. Usa la stessa icona per le pagine correlate:
| Argomento | Icona suggerita |
|---|---|
| Getting started | rocket |
| Authentication | lock |
| API reference | code |
| Settings | gear |
| Billing | 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: verifica:
- Virgolette mancanti attorno alle stringhe con caratteri speciali
- Rientro errato
- Due punti mancanti dopo le chiavi
Incolla il blocco tra i marcatori --- nel validatore YAML gratuito per individuare la riga e la colonna dell'errore.