# Sidebar

Pages that belong to a [group](/docs/groups) with a `sidebar` location get a two-column layout automatically. The sidebar shows the group's items as a navigation list with the current page highlighted.

## How does a page get a sidebar?

Add a `sidebar` location to a group in `settings/groups.md`, then make pages members of that group:

```yaml
# settings/groups.md
groups:
  - name: docs
    locations:
      - sidebar:
          - group: docs
    items:
      - Getting Started: /docs/getting-started
      - Themes: /docs/themes
```

```yaml
# pages/docs/themes.md frontmatter
groupMember:
  - docs
```

Every page with `groupMember: [docs]` now shows the docs sidebar. Override this per-page with `sidebarGroupShown`:

```yaml
sidebarGroupShown: docs    # force this group's sidebar
sidebarGroupShown: none    # suppress sidebar entirely
```

See [Groups](/docs/groups#locations) for the full location syntax, including targeting specific pages by file path.

## Search

The sidebar includes a scoped search bar. Click the magnifying glass icon or start typing to search within the current group's pages and the current page's headings.

Results are split into two sections:

| Section | What it searches |
|---|---|
| **This page** | Headings on the current page that match your query |
| **Other pages** | Pages in the same group, ranked by title and content match |

Selecting a result navigates to that page or heading and highlights the matched text. Use arrow keys to navigate results and Enter to select.

Site-wide search is always available via **⌘K** (Mac) or **Ctrl+K** (Windows/Linux), independent of the sidebar.

## Anchor navigation

Sidebar items can have nested anchors that link to sections within a page. These appear as an expandable sub-list below the parent link:

```yaml
# settings/groups.md
items:
  - Getting Started: /docs/getting-started
    - Install: #install
    - Connect Your Agent: #connect-your-agent
    - Build and Preview: #build-and-preview
```

Each anchor is a `- Label: #heading-id` entry indented under its parent item. The heading ID matches a `##` heading on that page — `## Install` becomes `#install`.

The active page's anchors expand automatically. Click the chevron to expand or collapse any section. As you navigate between anchor links, the active anchor is highlighted in the sidebar.

### Default display

Anchors are collapsed by default. To show all anchors expanded on load:

```yaml
groups:
  - name: docs
    anchorsDisplay: expanded
```

| Value | Behavior |
|---|---|
| `collapsed` | Anchors hidden until expanded. Active page always expands automatically. |
| `expanded` | All anchors visible on load. |

See [Groups — Sidebar Anchors](/docs/groups#sidebar-anchors) for details on finding heading IDs.

## How does the sidebar work on mobile?

On screens under 768px, the sidebar content moves into the hamburger menu. Open the menu and you'll see your site navigation at the top, followed by an "In this section" block containing the sidebar search and page links.

This means one tap opens everything — site nav, section nav, and search. Clicking any link in the menu closes it automatically, including anchor links that scroll within the current page.

The sidebar is not a separate toggle on mobile. It shares the same hamburger menu as the header navigation.

## Scrolling

On desktop, the sidebar is sticky — it stays visible as you scroll the page. When the sidebar content is taller than the viewport, a scrollbar appears so you can scroll the sidebar independently.

The scrollbar only renders when needed. Short sidebars with few items show no scrollbar. As you expand anchor sections or resize the browser, the scrollbar appears or disappears dynamically.

The active page link scrolls into view automatically on page load, so you always see where you are even in long sidebars.

## Related pages

- [Groups](/docs/groups) — define groups, locations, sidebar anchors, and item ordering
- [Navigation](/docs/navigation) — header nav setup and auto-scaffolding
- [Header](/docs/header) — search toggle, brand display, and full header reference