# How to structure a docs layout

A documentation layout has three fixed zones: navigation on the left, content in the middle, page index on the right. Everything else is detail.

> Page: https://ui.eneawork.it/blog/come-strutturare-un-layout-documentazione
> Markdown: https://ui.eneawork.it/blog/come-strutturare-un-layout-documentazione.md

*2026-11-01*

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.

Il catalogo EneUI conta 1.556 blocchi e 111.985 componenti da 1.472 librerie, misurati e letti da /api/stats il 1 novembre 2026. Solo 22 blocchi (1,4%) hanno la categoria sidebar, e arrivano da 2 delle 28 fonti; conteggio eseguito il 1 novembre 2026 su data/blocks.json, snapshot del 31 ottobre 2026. La misura riguarda i blocchi pubblicati nel catalogo, non i layout in uso nei progetti. Il comando è node -e "const b=require('./data/blocks.json').blocks;console.log(b.filter((x)=>(x.categories||[]).includes('sidebar')).length)" e stampa 22.

## 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.

## 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.

## FAQ

### Quante zone ha un layout di documentazione?

Tre: navigazione, contenuto, indice della pagina. Un header con la ricerca attraversa le tre zone ma non è una quarta colonna.

### La sidebar deve stare a sinistra?

Nella maggior parte dei casi sì, perché la lettura parte da sinistra. Su prodotti con più lingue o più prodotti, la scelta della lingua va sopra la navigazione.

### Dove metto l'indice della pagina?

A destra su schermi larghi, sotto il contenuto su schermi stretti. Non a sinistra: compete con la navigazione principale.

### Serve un framework per la documentazione?

No. Un layout statico con tre zone funziona con qualsiasi generatore; Fumadocs, licenza MIT, è una scelta comoda se usi Next.js.

### Come gestisco le pagine molto lunghe?

Spezza in sottopagine con un titolo che risponde a una domanda. Una pagina da quattromila parole non si legge e non si indicizza bene.