Blocks
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.
Key points
- Take navbar and sidebar from the same registry: they share the token scale.
- Anchors under a fixed header need scroll-margin, not a JavaScript offset.
- Three search blocks in the catalogue: you build the index yourself.
A documentation page has to make one sentence findable and one snippet copyable, not look like an encyclopedia. The catalogue indexes 9 navbar blocks, 27 sidebar, 3 search and 45 footer, read on 2026-11-01: four categories for a docs page.
The counts come from the public category pages and are the most useful data here: 3 search blocks out of a 1.556-block catalogue means search is the part no registry wants to publish. Treating it as solved because a box exists is buying a problem.
What the page has to do
Whoever reads documentation has already decided to use the product and is hunting a detail: a parameter name, a limit, a working example. The page should therefore favour text width, code copying and remembered position. It must also state which version it refers to, because half of the support questions start from stale docs.
- A nav bar with logo, version and search always reachable.
- A side tree that marks the active page after a refresh too.
- A code block with managed width and its own horizontal scroll.
- Copyable section links, so one support reply is a URL.
The order of the blocks
| Section | Role on the page | Blocks available |
|---|---|---|
| navbar | give logo, version and search | 9 |
| sidebar | show the page tree | 27 |
| search | find a sentence inside the text | 3 |
| footer | give licence, status and contacts | 45 |
Navbar, sidebar, search, footer: the navbar stays on top, the sidebar stays on the left and content lives in between. Swap navbar and sidebar and search ends up under the tree, hard to reach on mobile. The catalogue search comes from a topbar block: extract it from that context and adapt it, do not paste it as is.
The blocks from which to start
The tables list block, registry, files and category. The 11-file sidebar is the dense choice in the catalogue: it includes nested items, active state and a mobile variant. The 5-file navbar is deliberately minimal, so you add the version selector, and that work belongs in the estimate.
Navbar blocks
Sidebar blocks
| Block | Registry | File | Category |
|---|---|---|---|
| sidebar-15 | shadcn/ui | 11 | sidebar |
| sidebar-10 | shadcn/ui | 8 | sidebar |
Search blocks
| Block | Registry | File | Category |
|---|---|---|---|
| Topbar 06 - Search Focused Topbar | Shadcn Space | 7 | topbar |
| Global search | flx | 1 | global |
Footer blocks
| Block | Registry | File | Category |
|---|---|---|---|
| Footer 01 - Agency Footer Layout | Shadcn Space | 3 | footer |
| Footer 02 - Dark Conversion Footer | Shadcn Space | 2 | footer |
What breaks in production
The most frequent fault is the anchor that lands under the fixed header: you click an index entry and the heading stays covered. The second is code that breaks the column at 360 px and forces the page to scroll sideways, because the block declares no overflow. The third is the active item in the sidebar, lost when the page is reached from an external link.
- Covered anchors: needs scroll-margin-top equal to the header height.
- Code blocks without overflow: the page scrolls sideways.
- Sidebar with a fixed height: the last items are unreachable.
- Search that looks at titles only: the sentence you type does not exist.
curl "https://ui.eneawork.it/api/blocks/category/sidebar?limit=5"The call returns five sidebars with source and files: read it to see which include nested items and which are flat lists. A flat list needs a rewrite for three-level documentation, and the rewrite costs more than the block.
A limit to declare
With 3 search blocks and no tabs category at all, the catalogue covers the frame of documentation but not its main function. The search index, the section breadcrumb and the per-language tabs stay manual work: three components no block in here replaces.
In the catalogue: sidebar with state, responsive navbar and all blocks. The guides: mobile navbar, App Router structure and accessibility checklist.
Frequently asked questions
How wide should the text column be on a docs page?
Between 60 and 75 characters per line. Beyond that the eye loses the line return and reading slows; below it, lines break constantly and code wraps where it should not. Set the width on the container, not on the block.
Why only 3 search blocks in the catalogue?
Because real search needs an index, a server and result handling: no registry ships that as a copyable file. The three blocks are fields with a dropdown, useful as an interface, useless as an engine.
Should the sidebar stay open or collapse on mobile?
Collapsed, with a button that says “index” rather than an ambiguous icon. An open sidebar on a phone takes two thirds of the screen; collapsed, the page reads with one nav row and a jump to the index at the end.
Do internal anchors need JavaScript?
No, when you use scroll-margin-top on elements with an id. It is a supported CSS property and fixes the fixed header without listening to the click. The JavaScript that subtracts the header height goes away once the CSS lands, or the offset applies twice.
How do I mark the documentation version?
A selector in the navbar, with the current version always visible next to the logo and other versions reachable from a menu. The version also belongs in the URL, because a support link without a version ages without warning.