Come strutturare un layout di documentazione

Un layout di documentazione si struttura in tre zone fisse: navigazione a sinistra, contenuto al centro, indice della pagina a destra. Tutto il resto è dettaglio da aggiungere dopo.

Le tre zone e i loro vincoli

Ogni zona ha una regola che non dipende dal framework. Rispettala e il layout resta leggibile anche quando i contenuti cambiano.

• Sidebar: due livelli al massimo; il terzo livello diventa un indice nella pagina.
• Header: la ricerca e un solo link di uscita.
• Contenuto: una colonna, larghezza massima in caratteri, non in pixel.
• Indice: si aggiorna con lo scorrimento e non copre il testo.

Il comando

npx shadcn@latest add sidebar

Il comando installa il componente sidebar di shadcn/ui, licenza MIT, e scrive i file nel repository insieme alle dipendenze. Da lì la struttura della pagina è tua.

L'esempio concreto: l'albero come dato

La sidebar non è markup, è un array. Un nodo ha titolo, link e figli; il componente disegna due livelli e ignora il resto. Con questa forma, aggiungere una guida costa tre righe e nessun ritocco al CSS.

type Node = { title: string; href: string; children?: Node[] };

export const nav: Node[] = [
  { title: "Per iniziare", href: "/docs", children: [
    { title: "Installazione", href: "/docs/installazione" },
    { title: "Primo progetto", href: "/docs/primo-progetto" },
  ]},
  { title: "Guide", href: "/docs/guide", children: [
    { title: "Deploy", href: "/docs/guide/deploy" },
    { title: "Errori comuni", href: "/docs/guide/errori" },
  ]},
];

Il tipo Node vieta il terzo livello per costruzione: children esiste solo sul primo. Se un giorno serve un livello in più, il compilatore chiede di cambiare il tipo, e quella è la discussione da fare invece di annidare accordion.

Il record nel catalogo

Il record sidebar di shadcn/ui mostra file e comando; la categoria sidebar raccoglie i 22 blocchi completi, e la libreria Fumadocs, licenza MIT, è un layout di documentazione nato per i docs.

Contenuti lunghi, schermi piccoli

Su mobile l'indice a destra scende sotto il contenuto o sparisce in un pannello. Il titolo e il primo paragrafo restano in alto: se l'indice occupa il primo schermo, la risposta non si vede.

L'indice a destra è utile solo se resta visibile mentre scorri: position: sticky con un top pari all'altezza dell'header, e nessun max-height che tagli le ultime voci. Su una pagina con più di venti titoli l'indice diventa rumore: accorpa le sezioni prima di allungare la lista.

Un titolo raggiunto da un link interno finisce sotto l'header fisso se non riservi lo spazio: scroll-margin-top sull'elemento, pari all'altezza dell'header più sedici pixel, tiene il titolo visibile. Senza quel margine il lettore clicca una voce dell'indice e arriva a metà del paragrafo precedente.

La regola di decisione

Regola: quando una voce di primo livello supera sette figli, o compare un terzo livello, quella voce diventa una pagina indice con i suoi link. La sidebar resta a due livelli; il resto vive nel contenuto, dove la ricerca lo trova.

L'errore da evitare

Duplicare l'albero in due posti, nella sidebar e nell'indice in fondo alla pagina, senza una fonte sola: i due elenchi divergono entro il secondo mese e il lettore trova una guida nella sidebar che l'indice non nomina. Un array, due componenti, nessuna copia.

La limitazione

Il catalogo offre 22 blocchi sidebar su 1.556, e ognuno presuppone una forma di dati di navigazione diversa: non esiste un formato condiviso. Adattare un blocco a un albero di route reale resta lavoro manuale.

Dove continuare

Le quattro sezioni di una pagina docs sono in blocchi per la documentazione; l'installazione di un blocco è in come aggiungere un blocco shadcn; il confronto tra component library, UI kit e design system è in tre nomi diversi.