Guida - Aggiungere pagine e menu laterale

Questa guida spiega passo passo come aggiungere nuove pagine al sito e farle comparire nel menu laterale (sidebar).

Struttura del progetto

Il sito è basato su Astro 6 con Starlight 0.40. Le pagine di documentazione sono file .md o .mdx dentro src/content/docs/. Ogni file corrisponde automaticamente a una route (URL).

Esempio:

src/content/docs/
├── index.mdx              → /
├── miapagina.mdx          → /miapagina/
├── guides/
│   ├── example.md         → /guides/example/
│   └── aggiungere-pagine.mdx  → /guide/aggiungere-pagine/  (questa pagina)
└── reference/
    └── example.md         → /reference/example/

Passo 1: Creare un nuovo file

Crea un file .md o .mdx in src/content/docs/. Puoi usare sottocartelle per organizzare meglio.

Creare la cartella (opzionale) — Se vuoi raggruppare pagine per argomento, crea una sottocartella:
Terminal window
```
mkdir -p src/content/docs/argomenti
```

Creare il file — Crea un file, ad esempio src/content/docs/argomenti/cicli-csharp.mdx:

---
title: Cicli in C#
description: Guida ai cicli for, while e foreach in C#.
---

## Ciclo `for`

```csharp
for (int i = 0; i < 10; i++)
{
    Console.WriteLine(i);
}

Ciclo `foreach`

int[] numeri = { 1, 2, 3, 4, 5 };
foreach (var n in numeri)
{
    Console.WriteLine(n);
}

Aggiungere al menu laterale — Apri astro.config.mjs e aggiungi la nuova pagina nella sezione sidebar:

sidebar: [
    {
        label: 'Argomenti',
        items: [
            { label: 'Mia Pagina', slug: 'miapagina' },
            // Aggiungi qui le tue pagine:
            { label: 'Cicli C#', slug: 'argomenti/cicli-csharp' },
        ],
    },
],

Il campo slug è il percorso del file senza estensione e senza src/content/docs/.

---
title: Titolo pagina
description: Breve descrizione
---

## Contenuto

Testo normale, **grassetto**, `codice`, ecc.

L’MDX permette di usare componenti React/Astro dentro il Markdown:

---
title: Titolo pagina
description: Breve descrizione
---

import { Card, CardGrid } from '@astrojs/starlight/components';

## Contenuto

<CardGrid stagger>
    <Card title="Esempio" icon="pencil">
        Testo dentro una card.
    </Card>
</CardGrid>

Frontmatter: campi disponibili

Campo	Obbligatorio	Descrizione
`title`	✅	Titolo della pagina (appare anche nella sidebar)
`description`	✅	Descrizione breve (usata per SEO)
`prev`	❌	Nasconde il link “Pagina precedente” se `false`
`next`	❌	Nasconde il link “Pagina successiva” se `false`

La sidebar si configura in astro.config.mjs. Ecco le opzioni principali:

Pagine semplici

{ label: 'Nome link', slug: 'percorso/del/file' }

Sezioni con sottopagine

{
    label: 'Nome sezione',
    items: [
        { label: 'Sottopagina 1', slug: 'sezione/pagina1' },
        { label: 'Sottopagina 2', slug: 'sezione/pagina2' },
    ],
}

Generazione automatica

Puoi anche generare automaticamente il menu da una cartella:

{
    label: 'Riferimenti',
    items: [{ autogenerate: { directory: 'reference' } }],
}

Questo include tutti i file .md/.mdx dentro src/content/docs/reference/.

Riepilogo visivo

src/content/docs/                     astro.config.mjs
─────────────────────                 ────────────────────
index.mdx                             sidebar: [
miapagina.mdx  ────────────────→          { label: 'Mia Pagina', slug: 'miapagina' },
argomenti/
├── cicli-csharp.mdx  ──────────→          { label: 'Cicli C#', slug: 'argomenti/cicli-csharp' },
└── linq.mdx  ─────────────────→          { label: 'LINQ', slug: 'argomenti/linq' },

Comandi utili

Dopo aver aggiunto le pagine, verifica che tutto funzioni:

bun dev           # Avvia il server di sviluppo
bun astro check   # Controlla errori di tipo
bun build         # Build di produzione

📖 Documentazione ufficiale: Starlight Sidebar