Frontmatter
Configura titoli, descrizioni, icone, override della barra laterale e metadati SEO con il blocco YAML di frontmatter all'inizio 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 richiede almeno un titolo:
---
title: Getting Started
description: Learn the basics in 5 minutes
---Campi disponibili
Obbligatorio
| Campo | Tipo | Descrizione |
|---|---|---|
title | string | Titolo della pagina mostrato nella navigazione e nella scheda del browser |
Consigliato
| Campo | Tipo | Descrizione |
|---|---|---|
description | string | Breve riepilogo per SEO e risultati di ricerca (50-160 caratteri) |
Facoltativo
| Campo | Tipo | Predefinito | Descrizione |
|---|---|---|---|
icon | string | - | Icona Font Awesome mostrata accanto al titolo della pagina nella barra laterale |
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 piè di pagina social in questa pagina |
rss | boolean | false | Abilita la generazione del feed RSS dai componenti Update in questa pagina |
private | boolean | false | Richiede la password del sito per visualizzare questa pagina. L'impostazione di questo valore su qualsiasi pagina attiva la modalità pagine specifiche nella 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 sono impostati entrambi. |
SEO e social
Controlla come appare la pagina nei risultati di ricerca e nelle anteprime social. Imposta questi valori come chiavi principali o all'interno di un blocco annidato seo:. Entrambe le modalità funzionano e i valori per pagina sovrascrivono 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 di questa pagina, che sovrascrive quello generato automaticamente |
noindex | boolean | false | Esclude questa pagina dai motori di ricerca e dalla sitemap |
og:* / twitter:* | string | - | Tag per le anteprime social Open Graph e Twitter/X (ad esempio og:title, og:image, twitter:card) |
seo | object | - | Blocco annidato che contiene tutti i valori 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 altre piattaforme.
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à wide rimuove il sommario ed espande il contenuto a larghezza completa. È utile per le pagine di riferimento API o per i contenuti con tabelle ampie.
Nascondere il piè di pagina
---
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 appare:
- Nelle schede del browser
- Nei risultati dei motori di ricerca
- Nella barra laterale di navigazione
- Nelle 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
- Incoraggino 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 consigliata |
|---|---|
| Getting started | rocket |
| Authentication | lock |
| API reference | code |
| Settings | gear |
| Billing | credit-card |
Cerca 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 errato
- Due punti mancanti dopo le chiavi
Incolla il blocco tra i marcatori --- nel validatore YAML gratuito per individuare riga e colonna dell'errore.