Navigazione nella barra laterale

Una barra laterale ben organizzata è fondamentale per una buona documentazione poiché è uno dei modi principali in cui gli utenti navigheranno nel tuo sito. Starlight fornisce un set completo di opzioni per personalizzare il layout e il contenuto della barra laterale.

Barra laterale predefinita

Per impostazione predefinita, Starlight genererà automaticamente una barra laterale in base alla struttura del file system della documentazione, utilizzando la proprietà title di ciascun file come voce della barra laterale.

Ad esempio, data la seguente struttura di file:

Directorysrc/
- Directorycontent/
  - Directorydocs/
    Directoryguides/
    components.md
    i18n.md
    Directoryreference/
    configuration.md

Verrà generata automaticamente la seguente barra laterale:

guides
- Components
- Internationalization (i18n)
reference
- Configuration Reference

Scopri di più sulle barre laterali generate automaticamente nella sezione gruppi generati automaticamente.

Aggiungi collegamenti e gruppi di collegamenti

Per configurare i link e i gruppi di link della barra laterale (all’interno di un’intestazione comprimibile), utilizza la proprietà starlight.sidebar in astro.config.mjs.

Combinando collegamenti e gruppi, puoi creare un’ampia varietà di layout della barra laterale.

Collegamenti

Aggiungi un collegamento a una pagina interna o esterna utilizzando un oggetto con le proprietà label e link.

starlight({
  sidebar: [
    // Un collegamento alla guida CSS e stile.
    { label: 'CSS e stile', link: '/guides/css-and-tailwind/' },
    // Un collegamento esterno al sito web di Astro.
    { label: 'Astro', link: 'https://astro.build/' },
  ],
});

La configurazione sopra genera la seguente barra laterale:

Gruppi

Puoi aggiungere struttura alla barra laterale raggruppando i collegamenti correlati sotto un’intestazione comprimibile. I gruppi possono contenere sia collegamenti che altri sottogruppi.

Aggiungi un gruppo utilizzando un oggetto con le proprietà label e items. label verrà utilizzato come intestazione del gruppo. Aggiungi collegamenti o sottogruppi all’array items.

starlight({
  sidebar: [
    // Un gruppo di collegamenti etichettati "Guide".
    {
      label: 'Guide',
      items: [
        { label: 'Componenti', link: '/guides/components/' },
        { label: 'Internazionalizzazione (i18n)', link: '/guides/i18n/' },
        // Un gruppo nidificato di collegamenti.
        {
          label: 'Stile',
          items: [
            { label: 'CSS', link: '/guides/css-and-tailwind/' },
            { label: 'Tailwind', link: '/guides/css-and-tailwind/' },
            { label: 'Shiki', link: '/guides/css-and-tailwind/' },
          ],
        },
      ],
    },
  ],
});

La configurazione sopra genera la seguente barra laterale:

Guide
- Componenti
- Internazionalizzazione (i18n)
- Stile

Gruppi generati automaticamente

Starlight può generare automaticamente un gruppo nella barra laterale in base a una directory dei tuoi documenti. Ciò è utile quando non desideri inserire manualmente ciascun elemento della barra laterale in un gruppo.

Di default, le pagine sono ordinate in ordine alfabetico secondo lo slug del file.

Aggiungi un gruppo generato automaticamente utilizzando un oggetto con le proprietà label e autogenerate. La tua configurazione di autogenerate deve specificare quale directory da utilizzare per le voci della barra laterale. Ad esempio, con la seguente configurazione:

starlight({
  sidebar: [
    {
      label: 'Guides',
      // Genera automaticamente un gruppo di collegamenti per la directory 'guides'.
      autogenerate: { directory: 'guides' },
    },
  ],
});

E la seguente struttura di file:

Directorysrc/
- Directorycontent/
  - Directorydocs/
    Directoryguides/
    components.md
    i18n.md
    Directoryadvanced/
    project-structure.md

Verrà generata la seguente barra laterale:

Guides
- Components
- Internationalization (i18n)
- advanced
  - Project Structure

Personalizzazione dei collegamenti generati automaticamente nel frontmatter

Utilizza il campo frontmatter sidebar nelle singole pagine per personalizzare i collegamenti generati automaticamente.

Le opzioni frontmatter della barra laterale ti consentono di impostare un’etichetta personalizzata o aggiungere un badge a un collegamento, nascondi un collegamento dalla barra laterale o definire un ponderazione dell’ordinamento personalizzato.

---
title: La mia pagina
sidebar:
  # Imposta un'etichetta personalizzata per il collegamento
  label: etichetta personalizzata della barra laterale
  # Imposta un ordine personalizzato per il collegamento (i numeri inferiori vengono visualizzati più in alto)
  order: 2
  # Aggiungi un badge al collegamento
  badge:
    text: Nuovo
    variant: tip
---

Un gruppo generato automaticamente che include una pagina con il frontmatter sopra genererà la seguente barra laterale:

Guide

Badge

I collegamenti, i gruppi e i gruppi generati automaticamente possono anche includere una proprietà badge per visualizzare un badge accanto all’etichetta del collegamento.

starlight({
  sidebar: [
    {
      label: 'Guide',
      items: [
        // Un link con il badge "Nuovo".
        {
          label: 'Componenti',
          link: '/guides/components/',
          badge: 'Nuovo',
        },
      ],
    },
    // Un gruppo autogenerato con il badge "Deprecato".
    {
      label: 'Riferimento',
      badge: 'Deprecato',
      autogenerate: { directory: 'reference' },
    },
  ],
});

La configurazione sopra genera la seguente barra laterale:

Guide
- Componenti Nuovo
Riferimento Deprecato

Varianti del badge

Personalizza lo stile del badge utilizzando un oggetto con proprietà text e variant.

Il text rappresenta il contenuto da visualizzare (ad esempio “Nuovo”). Sostituisci lo stile default, che utilizza il colore in risalto del tuo sito, impostando la proprietà variant su uno dei seguenti valori: note, tip, danger, caution o success.

starlight({
  sidebar: [
    {
      label: 'Guide',
      items: [
        // Un collegamento con un badge giallo "Sperimentale".
        {
          label: 'Componenti',
          link: '/guides/components/',
          badge: { text: 'Sperimentale', variant: 'caution' },
        },
      ],
    },
  ],
});

La configurazione sopra genera la seguente barra laterale:

Guide
- Componenti Sperimentale

Attributi HTML personalizzati

I collegamenti possono anche includere una proprietà attrs per aggiungere attributi HTML personalizzati all’elemento collegamento.

Nell’esempio seguente, attrs viene utilizzato per aggiungere un attributo target="_blank", in modo che il collegamento si apra in una nuova scheda e per applicare un attributo personalizzato style per scrivere in corsivo l’etichetta del collegamento:

starlight({
  sidebar: [
    {
      label: 'Guide',
      items: [
        // Un collegamento esterno alla documentazione di Astro che si apre in una nuova scheda.
        {
          label: 'Documentazione di Astro',
          link: 'https://docs.astro.build/',
          attrs: { target: '_blank', style: 'font-style: italic' },
        },
      ],
    },
  ],
});

La configurazione sopra genera la seguente barra laterale:

Guide
- Documentazione di Astro

Internazionalizzazione

Utilizza la proprietà translations su voci di link e gruppi per tradurre l’etichetta del link o del gruppo per ogni lingua supportata specificando un tag di lingua BCP-47, ad esempio "en", "ar", o "zh-CN", come chiave e l’etichetta tradotta come valore. La proprietà label sarà utilizzata per la lingua predefinita e per le lingue senza traduzione.

starlight({
  sidebar: [
    {
      label: 'Guides',
      translations: {
        'pt-BR': 'Guias',
      },
      items: [
        {
          label: 'Components',
          translations: {
            'pt-BR': 'Componentes',
          },
          link: '/guides/components/',
        },
        {
          label: 'Internationalization (i18n)',
          translations: {
            'pt-BR': 'Internacionalização (i18n)',
          },
          link: '/guides/i18n/',
        },
      ],
    },
  ],
});

La navigazione della documentazione in Portoghese (Brasile) genererà la seguente barra laterale:

Guias
- Componentes
- Internacionalização (i18n)

Gruppi compressi

I gruppi di collegamenti possono essere compressi per impostazione predefinita impostando la proprietà collapsed su true.

starlight({
  sidebar: [
    {
      label: 'Guide',
      // Comprimi il gruppo per impostazione predefinita.
      collapsed: true,
      items: [
        { label: 'Componenti', link: '/it/guides/components/' },
        { label: 'Internazionalizzazione (i18n)', link: '/it/guides/i18n/' },
      ],
    },
  ],
});

La configurazione sopra genera la seguente barra laterale:

Guide
- Componenti
- Internazionalizzazione (i18n)

I gruppi generati automaticamente rispettano il valore collapsed del gruppo principale:

starlight({
  sidebar: [
    {
      label: 'Guide',
      // Comprimi il gruppo e i relativi sottogruppi generati automaticamente per impostazione predefinita.
      collapsed: true,
      autogenerate: { directory: 'guides' },
    },
  ],
});

La configurazione sopra genera la seguente barra laterale:

Guide
- Componenti
- Internazionalizzazione (i18n)
- advanced
  - Struttura del progetto

Questo comportamento può essere ignorato definendo la proprietà autogenerate.collapsed.

starlight({
  sidebar: [
    {
      label: 'Guide',
      // Non comprimere il gruppo "Guide", ma comprimerlo
      // sottogruppi generati automaticamente.
      collapsed: false,
      autogenerate: { directory: 'guides', collapsed: true },
    },
  ],
});

La configurazione sopra genera la seguente barra laterale:

Guide
- Componenti
- Internazionalizzazione (i18n)
- advanced
  - Struttura del progetto