# 4 blocks for a documentation page

A documentation page has to make one sentence findable and one snippet copyable. Four categories, the order between navbar and sidebar, the anchor faults and the real catalogue counts.

> Page: https://ui.eneawork.it/blog/blocchi-per-documentazione
> Markdown: https://ui.eneawork.it/blog/blocchi-per-documentazione.md

*2026-10-31*

Una pagina di documentazione deve far trovare una frase e copiare uno snippet, non sembrare un'enciclopedia. Il catalogo indicizza 9 blocchi navbar, 27 sidebar, 3 search e 45 footer, letti il 2026-11-01: quattro categorie per una pagina docs.

I conteggi vengono dalle pagine categoria pubbliche ed è il dato più utile di questa pagina, misurato lo stesso giorno: 3 blocchi search su un catalogo di 1.556 significa che la ricerca è la parte che nessun registry vuole pubblicare. Chi la considera risolta perché c'è una casella sta comprando un problema.

## Cosa deve fare la pagina

Chi legge documentazione ha già deciso di usare il prodotto e sta cercando un dettaglio: un nome di parametro, un limite, un esempio funzionante. La pagina deve quindi privilegiare la larghezza del testo, la copia del codice e la memoria della posizione. Deve anche dire a quale versione si riferisce, perché metà delle domande di supporto nasce da documentazione vecchia.

## L'ordine dei blocchi

Navbar, sidebar, search, footer: la navbar resta in cima, la sidebar resta a sinistra e il contenuto vive in mezzo. Se inverti navbar e sidebar, la ricerca finisce sotto l'albero e diventa difficile da raggiungere su mobile. La ricerca del catalogo arriva da un blocco topbar: va estratta dal contesto e adattata, non incollata così com'è.

## I blocchi da cui partire

Le tabelle riportano blocco, registry, file e categoria. La sidebar da 11 file è la scelta densa del catalogo: include voci annidate, stato attivo e variante mobile. La navbar da 5 file è volutamente minima, quindi il selettore di versione lo aggiungi tu, e quel lavoro va messo nel preventivo.

## Blocchi navbar

## Blocchi sidebar

## Blocchi search

## Blocchi footer

## Cosa si rompe in produzione

Il guasto più frequente è l'anchor che finisce sotto l'header fisso: clicchi una voce dell'indice e il titolo resta coperto. Il secondo è il codice che sfonda la colonna a 360 px e costringe la pagina a scorrere in orizzontale, perché il blocco non dichiara overflow. Il terzo è la voce attiva nella sidebar, che si perde quando la pagina è raggiunta da un link esterno.

curl "https://ui.eneawork.it/api/blocks/category/sidebar?limit=5"

La chiamata restituisce cinque sidebar con fonte e file: leggila per vedere quali includono voci annidate e quali sono elenchi piatti. Un elenco piatto va riscritto per una documentazione a tre livelli, e la riscrittura costa più del blocco.

Navbar e sidebar dallo stesso registry, sempre: due fonti diverse portano radius e spaziature differenti, e la cucitura si vede esattamente dove il lettore guarda di più.

## Un limite da dichiarare

Con 3 blocchi search e nessuna categoria tabs, il catalogo copre la cornice della documentazione ma non la sua funzione principale. L'indice di ricerca, il breadcrumb di sezione e le schede per linguaggio restano lavoro manuale: sono tre componenti che nessun blocco qui dentro sostituisce.

Nel catalogo: sidebar con stato, navbar responsive e tutti i blocchi. Le guide: navbar mobile, struttura App Router e checklist accessibilità.

## FAQ

### Quanto deve essere larga la colonna di testo in una pagina docs?

Tra 60 e 75 caratteri per riga. Oltre, l'occhio perde il ritorno a capo e la lettura rallenta; sotto, le righe si spezzano in continuazione e il codice va a capo dove non dovrebbe. La larghezza si imposta sul contenitore, non sul blocco.

### Perché solo 3 blocchi search nel catalogo?

Perché una ricerca vera richiede un indice, un server e una gestione dei risultati: nessun registry può consegnarla come file copiabile. I tre blocchi sono campi con dropdown, utili come interfaccia, inutili come motore.

### Meglio la sidebar sempre aperta o a scomparsa su mobile?

A scomparsa, con un bottone che dice «indice» e non un'icona ambigua. La sidebar aperta su un telefono occupa due terzi dello schermo; chiusa, la pagina si legge con una riga di navigazione e un salto all'indice in fondo.

### Gli anchor interni hanno bisogno di JavaScript?

No, se usi scroll-margin-top sugli elementi con id. È una proprietà CSS supportata e risolve l'header fisso senza ascoltare il click. Il codice JavaScript che sottrae l'altezza dell'header va tolto quando arriva il CSS, altrimenti l'offset si somma due volte.

### Come indico la versione della documentazione?

Un selettore nella navbar, con la versione corrente sempre visibile accanto al logo e le altre versioni raggiungibili da un menu. La versione va anche nell'URL, perché un link di supporto senza versione invecchia senza avvisare.