Navigation and tabs

With no configuration, the sidebar mirrors your folder structure: directories become groups, pages sort inside them, and the home page leads. Configuration replaces that ordering when you want to curate it.

Explicit navigation

List slugs in the order you want, nesting groups freely:

navigation:
  - index
  - group: Start here
    pages:
      - what-is-readsmith
      - quickstart
  - group: Guides
    pages:
      - guides/setup
      - group: Advanced
        pages:
          - guides/scaling

Rules the build enforces for you:

• A slug that matches no page is reported at build time, not discovered by a reader.
• Hidden pages never appear, even when listed.
• Pages left out of an explicit navigation stay reachable at their URLs; they are unlisted from the sidebar only.

Tabs

Tabs split large sites into top-level sections, each with its own sidebar:

tabs:
  - tab: Guides
    pages:
      - index
      - group: Start here
        pages: [what-is-readsmith, quickstart]
  - tab: Components
    pages:
      - components/overview

The active tab scopes the sidebar, breadcrumbs, and previous/next links, so readers move within a section rather than across the whole site. This site's own tab row is exactly this configuration.

Group icons, tags, and default state

A group can carry an icon, a small tag, and its default open or closed state:

navigation:
  - group: Guides
    icon: book-open        # a Lucide icon name, resolved to inline SVG at build
    expanded: true         # open by default (groups start collapsed otherwise)
    pages: [quickstart, authoring/pages]
  - group: Reference
    icon: braces
    tag: Beta              # a small badge beside the group label
    pages: [api-reference-guide/setup]

Icons are drawn from the bundled Lucide set, so no name reaches the network. tag is plain text.

Dropdown menus on tabs

A tab can be a dropdown instead of a single destination. Give it a menu of items, each with its own pages and optional icon:

tabs:
  - tab: Products
    icon: box
    menu:
      - item: Core API
        icon: server
        pages: [api-reference-guide/setup]
      - item: Webhooks
        icon: webhook
        pages: [guides/webhooks]

The tab opens a menu of its items; selecting one scopes the sidebar to that item's pages. The disclosure works without JavaScript and is keyboard-operable. A tab without a menu stays a plain link.

The API reference joins the row

With apiReference.layout: pages, the generated reference appears as its own tab, a complete catalog of every operation. An operation page you explicitly place in another tab keeps that home, and the catalog still lists it so the reference stays complete. With the single-page layout, the reference is linked from the header instead.

Labels

The sidebar shows each page's title, unless the page sets a shorter sidebarTitle:

---
title: Deploying behind a corporate reverse proxy
sidebarTitle: Reverse proxy
---