Design documentation navigation that scales

Readers use a documentation sidebar to answer three questions: Where am I? What sits beside this page? Where should I look for a different kind of answer? A useful structure makes those answers visible without turning every folder into a control.

Ginko Docs derives the sidebar from the content tree. That keeps file order, public routes, breadcrumbs, previous and next links, and search navigation aligned. The design work therefore happens in the content structure, not in a second frontend menu.

Start with reader intent

Separate pages that teach from pages that list. A quickstart should lead to a working result. A guide should complete one task. A reference page should describe one public surface exhaustively.

When these page types share an undifferentiated list, readers cannot tell whether a link will teach a workflow or present an option table. Broad sections such as Documentation and Reference provide that first decision. Local groups such as Authoring, Features, or Components make the next decision smaller.

Give each level one job

Use sidebar: section for the major areas shown by the section switcher. Use sidebar: group for a visible heading within the current section. Leave an ordinary folder unmarked only when its children form a real nested topic that readers should expand and collapse.

Keep the common path shallow:

section → group → page

A fourth level can be useful for genuine variants, such as separate Nuxt and Vue installation instructions. It should not exist only because the source files were convenient to store in another folder.

Make index pages earn their route

An index page is useful when it orients the reader, defines a concept shared by its children, or helps someone choose among several paths. An index page that only lists the same links already visible in the sidebar adds another stop without adding information.

Structural groups do not need an index page. The sidebar can show the label while the section switcher resolves to the first real page.

Design desktop and mobile together

Desktop has room for the document tree and the current page's table of contents at the same time. Mobile does not. Keep those controls separate: one answers “Which page?” and the other answers “Which heading on this page?” Combining them saves one button but mixes two navigation models.

Search is a third path, not a replacement for structure. It helps readers who know the words they want. The sidebar still serves readers who are learning the vocabulary of the product.

The navigation guide describes the exact sidecar metadata. When the corpus changes, review the structure by reader task and scan depth—not by whether every folder appears somewhere on screen.