Blocks
4 blocchi per una pagina documentazione
Una pagina di documentazione deve far trovare una frase e copiare uno snippet. Quattro categorie, l'ordine tra navbar e sidebar, i guasti degli anchor e i conteggi reali del catalogo.
In sintesi
- Navbar e sidebar vanno prese dallo stesso registry: condividono la scala dei token.
- Gli anchor con header fisso richiedono scroll-margin, non un offset in JavaScript.
- Tre blocchi search nel catalogo: l'indice lo costruisci tu.
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.
- Una riga di navigazione con logo, versione e ricerca sempre raggiungibile.
- Un albero laterale che segna la pagina attiva anche dopo un refresh.
- Un blocco codice con larghezza gestita e scroll orizzontale proprio.
- Link di sezione copiabili, così una risposta di supporto è un URL.
L'ordine dei blocchi
| Sezione | Ruolo nella pagina | Blocchi disponibili |
|---|---|---|
| navbar | dare logo, versione e ricerca | 9 |
| sidebar | mostrare l'albero delle pagine | 27 |
| search | trovare una frase dentro i testi | 3 |
| footer | dare licenza, stato e contatti | 45 |
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
| Blocco | Registry | File | Categoria |
|---|---|---|---|
| sidebar-15 | shadcn/ui | 11 | sidebar |
| sidebar-10 | shadcn/ui | 8 | sidebar |
Blocchi search
| Blocco | Registry | File | Categoria |
|---|---|---|---|
| Topbar 06 - Search Focused Topbar | Shadcn Space | 7 | topbar |
| Global search | flx | 1 | global |
Blocchi footer
| Blocco | Registry | File | Categoria |
|---|---|---|---|
| Footer 01 - Agency Footer Layout | Shadcn Space | 3 | footer |
| Footer 02 - Dark Conversion Footer | Shadcn Space | 2 | 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.
- Anchor coperti: serve scroll-margin-top pari all'altezza dell'header.
- Blocchi codice senza overflow: la pagina scorre in orizzontale.
- Sidebar con altezza fissa: le voci in fondo non si raggiungono.
- Ricerca che cerca solo nei titoli: la frase cercata non esiste.
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.
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à.
Domande frequenti
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.