How to structure a docs layout

A documentation layout is built from three fixed zones: navigation on the left, content in the middle, the page index on the right. Everything else is detail you add later.

The three zones and their constraints

Each zone has one rule that does not depend on the framework. Follow it and the layout stays readable when the content changes.

• Sidebar: two levels at most; a third level becomes an index inside the page.
• Header: search plus one exit link.
• Content: one column, with a maximum width in characters, not pixels.
• Index: it updates on scroll and never covers the text.

The command

npx shadcn@latest add sidebar

The command installs the shadcn/ui sidebar component under the MIT licence, writing the files into your repository along with the dependencies. From there the page structure is yours.

A concrete example: the tree as data

The sidebar is not markup, it is an array. A node has a title, a link and children; the component draws two levels and ignores the rest. With that shape, adding a guide costs three lines and no CSS work.

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" },
  ]},
];

The Node type forbids the third level by construction: children exist only on the first level. If a deeper level is ever needed, the compiler asks for a type change, and that is the conversation to have instead of nesting accordions.

The record in the catalogue

The shadcn/ui sidebar record shows files and command; the sidebar category collects the 22 complete blocks, and the Fumadocs library, MIT licence, is a documentation layout built for docs.

Long content, small screens

On mobile the right-hand index moves below the content or into a panel. The title and the first paragraph stay at the top: if the index owns the first screen, the answer is invisible.

The right-hand index only helps while it stays visible as you scroll: position: sticky with a top equal to the header height, and no max-height that cuts the last entries. On a page with more than twenty headings the index turns into noise: merge sections before you make the list longer.

A heading reached from an internal link lands under the fixed header unless you reserve the space: scroll-margin-top on the element, equal to the header height plus sixteen pixels, keeps the heading visible. Without that margin the reader clicks an index entry and arrives halfway through the previous paragraph.

The decision rule

Rule: when a top-level entry grows past seven children, or a third level appears, that entry becomes an index page with its own links. The sidebar stays at two levels; the rest lives in the content, where search can find it.

The mistake to avoid

Duplicating the tree in two places, the sidebar and the list at the end of the page, with no single source: the two lists drift apart within the second month and the reader finds a guide in the sidebar that the index never names. One array, two components, no copies.

The limitation

The catalogue offers 22 sidebar blocks out of 1,556, and each assumes a different navigation data shape: no shared format exists. Adapting a block to a real route tree stays manual work.

Where to continue

The four sections of a docs page are in blocks for documentation; installing a block is covered in how to add a shadcn block; the comparison of component library, UI kit and design system is in three different names.