Salta ai contenuti
Starlight
Filters

    Riferimenti frontmatter

    Puoi personalizzare pagine Markdown e MDX in Starlight definendo i valori nel frontmatter. Per esempio, una pagina potrebbe definire title e description :

    src/content/docs/example.md
    ---
    title: A proposito del progetto
    description: Scopri di più sul progetto a cui sto lavorando.
    ---
    

    Benvenuto alla pagina "a proposito del progetto"!

    Campi del frontmatter

    Sezione intitolata “Campi del frontmatter”

    title (obbligatorio)

    Sezione intitolata “title (obbligatorio)”

    tipo: string

    Devi fornire un titolo ad ogni pagina. Questo sarà usato in testa alla pagina, nelle finestre del browser e nei metadati della pagina.

    description

    Sezione intitolata “description”

    tipo: string

    La descrizione è utilizzata nei metadati e sarà utilizzata dai motori di ricerca e nelle anteprime nei social.

    slug

    Sezione intitolata “slug”

    tipo:: string

    Sovrascrivi lo slug della pagina. Vedi “Definizione degli slug personalizzati” nella documentazione di Astro per ulteriori dettagli.

    editUrl

    Sezione intitolata “editUrl”

    tipo: string | boolean

    Sovrascrive la configurazione globale editLink. Metti a false per disabilitare “Modifica la pagina” per quella pagina specifica oppure fornisci un link alternativo.

    Sezione intitolata “head”

    tipo: HeadConfig[]

    Puoi aggiungere tag aggiuntivi nell’<head> della pagina utilizzando la chiave head nel frontmatter. Questo significa che puoi aggiungere stili personalizzati, metadati o altri tag in una pagina. Il funzionamento è simile all’opzione globale head.

    src/content/docs/example.md
    ---
    title: Chi siamo
    head:
      # Utilizza un <title> personalizzato
      - tag: title
        content: Titolo personalizzato
    ---

    tableOfContents

    Sezione intitolata “tableOfContents”

    tipo: false | { minHeadingLevel?: number; maxHeadingLevel?: number; }

    Sovrascrive la configurazione globale tableOfContents. Cambia i livelli di titoli inclusi o, se messo a false, nasconde la tabella dei contenuti della pagina.

    src/content/docs/example.md
    ---
    title: Pagina con solo H2 nella tabella dei contenuti della pagina
    tableOfContents:
      minHeadingLevel: 2
      maxHeadingLevel: 2
    ---
    src/content/docs/example.md
    ---
    title: Pagina senza tabella dei contenuti della pagina
    tableOfContents: false
    ---

    template

    Sezione intitolata “template”

    tipo: 'doc' | 'splash'
    predefinito: 'doc'

    Definisce il layout per la pagina. Le pagine utilizzano 'doc' come predefinita. Se valorizzato a 'splash' viene utilizzato un layout senza barre laterali ottimale per la pagina iniziale.

    hero

    Sezione intitolata “hero”

    tipo: HeroConfig

    Aggiunge un componente hero all’inizio della pagina. Funziona bene con template: splash.

    Per esempio, questa configurazione illustra comuni opzioni, incluso il caricamento di un’immagine.

    src/content/docs/example.md
    ---
    title: La mia pagina principale
    template: splash
    hero:
      title: 'Il mio progetto: Stellar Stuff Sooner'
      tagline: Porta le tue cose sulla Luna e torna indietro in un battito d'occhio.
      image:
        alt: Un logo brillante e luminoso
        file: ../../assets/logo.png
      actions:
        - text: Dimmi di più
          link: /getting-started/
          icon: right-arrow
          variant: primary
        - text: Vedi su GitHub
          link: https://github.com/astronaut/my-project
          icon: external
          attrs:
            rel: me
    ---

    Puoi mostrare diverse versioni dell’immagine in base alla modalità chiara o scura.

    src/content/docs/example.md
    ---
    hero:
      image:
        alt: Un logo brillante e luminoso
        dark: ~/assets/logo-dark.png
        light: ~/assets/logo-light.png
    ---

    HeroConfig

    Sezione intitolata “HeroConfig”
    interface HeroConfig {
      title?: string;
      tagline?: string;
      image?:
        | {
            // Percorso relativo a un'immagine nella tua repository.
            file: string;
            // Testo alternativo per rendere l'immagine accessibile alla tecnologia assistiva
            alt?: string;
          }
        | {
            // Percorso relativo a un'immagine nella tua repository da utilizzare per la modalità scura.
            dark: string;
            // Percorso relativo a un'immagine nella tua repository da utilizzare per la modalità chiara.
            light: string;
            // Testo alternativo per rendere l'immagine accessibile alla tecnologia assistiva
            alt?: string;
          }
        | {
            // HTML grezzo da utilizzare nello slot dell'immagine.
            // Potrebbe essere un tag `<img>` personalizzato o `<svg>` inline.
            html: string;
          };
      actions?: Array<{
        text: string;
        link: string;
        variant: 'primary' | 'secondary' | 'minimal';
        icon: string;
        attrs?: Record<string, string | number | boolean>;
      }>;
    }
    Sezione intitolata “banner”

    tipo: { content: string }

    Visualizza un banner di annuncio nella parte superiore di questa pagina.

    Il valore content può includere HTML per collegamenti o altri contenuti. Ad esempio, questa pagina visualizza un banner che include un collegamento a example.com.

    src/content/docs/example.md
    ---
    title: Pagina con un banner
    banner:
      content: |
        Abbiamo appena lanciato qualcosa di interessante!
        <a href="https://example.com">Dai un'occhiata</a>
    ---

    lastUpdated

    Sezione intitolata “lastUpdated”

    tipo: Date | boolean

    Sostituisce l’opzione globale lastUpdated. Se viene specificata una data, deve essere un timestamp YAML valido e sovrascriverà la data archiviata nella cronologia Git per questa pagina.

    src/content/docs/example.md
    ---
    title: Pagina con una data di ultimo aggiornamento personalizzata
    lastUpdated: 2022-08-09
    ---

    prev

    Sezione intitolata “prev”

    tipo: boolean | string | { link?: string; label?: string }

    Sostituisce l’opzione globale paginazione. Se viene specificata una stringa, il testo del collegamento generato verrà sostituito e se viene specificato un oggetto, sia il collegamento che il testo verranno sovrascritti.

    src/content/docs/example.md
    ---
    # Nascondi il collegamento alla pagina precedente
    prev: false
    ---
    src/content/docs/example.md
    ---
    # Sostituisci il testo del collegamento della pagina precedente
    prev: Continua il tutorial
    ---
    src/content/docs/example.md
    ---
    # Sostituisci sia il collegamento che il testo della pagina precedente
    prev:
      link: /pagina-non-correlata/
      label: Dai un'occhiata a quest'altra pagina
    ---

    next

    Sezione intitolata “next”

    tipo: boolean | string | { link?: string; label?: string }

    Uguale a prev ma per il collegamento alla pagina successiva.

    src/content/docs/example.md
    ---
    # Nascondi il collegamento alla pagina successiva
    next: false
    ---

    pagefind

    Sezione intitolata “pagefind”

    tipo: boolean
    predefinito: true

    Imposta se questa pagina deve essere inclusa nell’indice di ricerca Pagefind. Imposta su false per escludere una pagina dai risultati di ricerca:

    src/content/docs/example.md
    ---
    # Nascondi questa pagina dai risultati di ricerca
    pagefind: false
    ---

    draft

    Sezione intitolata “draft”

    tipo: boolean
    predefinito: false

    Imposta se questa pagina deve essere considerata una bozza e non essere inclusa nelle build di produzione e nei gruppi di link autogenerati. Imposta su true per contrassegnare una pagina come bozza e renderla visibile solo durante lo sviluppo.

    src/content/docs/example.md
    ---
    # Escludi questa pagina dalle build di produzione
    draft: true
    ---
    Sezione intitolata “sidebar”

    tipo: SidebarConfig

    Controlla il modo in cui questa pagina viene visualizzata nella barra laterale, quando si utilizza un gruppo di collegamenti generato automaticamente.

    SidebarConfig

    Sezione intitolata “SidebarConfig”
    interface SidebarConfig {
      label?: string;
      order?: number;
      hidden?: boolean;
      badge?: string | BadgeConfig;
      attrs?: Record<string, string | number | boolean | undefined>;
    }

    label

    Sezione intitolata “label”

    tipo: string
    predefinito: la pagina title

    Imposta l’etichetta per questa pagina nella barra laterale quando viene visualizzata in un gruppo di collegamenti generato automaticamente.

    src/content/docs/example.md
    ---
    title: Informazioni su questo progetto
    sidebar:
      label: Informazioni
    ---

    order

    Sezione intitolata “order”

    tipo: number

    Controlla l’ordine di questa pagina quando ordini un gruppo di collegamenti generato automaticamente. I numeri più bassi vengono visualizzati più in alto nel gruppo di collegamenti.

    src/content/docs/example.md
    ---
    title: Pagina da visualizzare per prima
    sidebar:
      order: 1
    ---

    hidden

    Sezione intitolata “hidden”

    tipo: boolean
    predefinito: false

    Impedisce che questa pagina venga inclusa in un gruppo della barra laterale generato automaticamente.

    src/content/docs/example.md
    ---
    title: Pagina da nascondere dalla barra laterale generata automaticamente
    sidebar:
      hidden: true
    ---

    badge

    Sezione intitolata “badge”

    tipo: string | BadgeConfig

    Aggiungi un badge alla pagina nella barra laterale quando viene visualizzata in un gruppo di collegamenti generato automaticamente. Quando si utilizza una stringa, il badge verrà visualizzato con un colore in risalto predefinito. Facoltativamente, passa un oggetto BadgeConfig con i campi text, variant e class per personalizzare il badge.

    src/content/docs/example.md
    ---
    title: Pagina con un badge
    sidebar:
      # Utilizza la variante predefinita corrispondente al colore principale del tuo sito
      badge: nuovo
    ---
    src/content/docs/example.md
    ---
    title: Pagina con un badge
    sidebar:
      badge:
        text: Sperimentale
        variant: caution
    ---

    attrs

    Sezione intitolata “attrs”

    tipo: Record<string, string | number | boolean | undefined>

    Attributi HTML da aggiungere al collegamento della pagina nella barra laterale quando viene visualizzato in un gruppo di collegamenti generato automaticamente.

    src/content/docs/example.md
    ---
    title: Pagina che si aprirà in una nuova scheda
    sidebar:
      # Apre la pagina in una nuova scheda
      attrs:
        target: _blank
    ---

    Personalizza lo schema del frontmatter

    Sezione intitolata “Personalizza lo schema del frontmatter”

    Lo schema del frontmatter per la raccolta di contenuti docs di Starlight è configurato in src/content/config.ts utilizzando l’helper docsSchema():

    src/content/config.ts
    import { defineCollection } from 'astro:content';
    import { docsSchema } from '@astrojs/starlight/schema';
    

    export const collections = {
      docs: defineCollection({ schema: docsSchema() }),
    };

    Per saperne di più sugli schemi di raccolta dei contenuti, consulta “Definizione di uno schema di raccolta” nella documentazione di Astro.

    docsSchema() accetta le seguenti opzioni:

    extend

    Sezione intitolata “extend”

    tipo: Schema Zod o funzione che restituisce uno schema Zod
    predefinito: z.object({})

    Estendi lo schema di Starlight con campi aggiuntivi impostando extend nelle opzioni di docsSchema(). Il valore dovrebbe essere uno schema Zod.

    Nell’esempio seguente, forniamo un tipo più restrittivo per description per renderlo obbligatorio e aggiungiamo un nuovo campo opzionale category:

    src/content/config.ts
    import { defineCollection, z } from 'astro:content';
    import { docsSchema } from '@astrojs/starlight/schema';
    

    export const collections = {
      docs: defineCollection({
        schema: docsSchema({
          extend: z.object({
            // Rendi un campo built-in obbligatorio anziché opzionale.
            description: z.string(),
            // Aggiungi un nuovo campo allo schema.
            category: z.enum(['tutorial', 'guide', 'reference']).optional(),
          }),
        }),
      }),
    };

    Per sfruttare l’helper image() di Astro,, utilizza una funzione che restituisce l’estensione dello schema:

    src/content/config.ts
    import { defineCollection, z } from 'astro:content';
    import { docsSchema } from '@astrojs/starlight/schema';
    

    export const collections = {
      docs: defineCollection({
        schema: docsSchema({
          extend: ({ image }) => {
            return z.object({
              // Aggiungi un campo che deve risolvere in un'immagine locale.
              cover: image(),
            });
          },
        }),
      }),
    };