---
title: Navigation
description: Navigation in Jamdesk uses tabs, groups, and pages to organize your documentation. External links can be added using anchors.
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

Your sidebar and top bar are defined entirely in `docs.json`. The navigation hierarchy has three levels -- tabs for top-level sections, groups for collapsible folders, and pages for individual entries -- plus anchors for external links that appear on every page.

## Structure Overview

```json docs.json
{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "icon": "book-open",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      }
    ]
  }
}
```

## Concepts

### Tabs

Top-level navigation sections. Control their position with the `tabsPosition` setting:

| Value    | Position                  |
| -------- | ------------------------- |
| `"top"`  | In the header tab bar     |
| `"left"` | At the top of the sidebar |

The default position depends on your theme:

| Theme  | Default  |
| ------ | -------- |
| jam    | `"left"` |
| nebula | `"left"` |
| pulsar | `"top"`  |

```json
{
  "tabsPosition": "left",
  "navigation": {
    "tabs": [
      { "tab": "Guides", "icon": "book", "groups": [...] },
      { "tab": "API", "icon": "code", "groups": [...] }
    ]
  }
}
```

<Note>
  Icons use the Font Awesome Light variant to maintain a clean, consistent
  appearance.
</Note>

### External Links (Anchors)

Add external links that appear at the top of the sidebar on all pages:

```json
{
  "anchors": [
    { "name": "Blog", "href": "https://blog.example.com", "icon": "newspaper" },
    { "name": "Status", "href": "https://status.example.com", "icon": "signal" }
  ]
}
```

| Field  | Type   | Required | Description               |
| ------ | ------ | -------- | ------------------------- |
| `name` | string | Yes      | Display text for the link |
| `href` | string | Yes      | URL (opens in new tab)    |
| `icon` | string | No       | Font Awesome icon name    |

### Groups

A group is a labeled set of sidebar entries inside a tab. Groups give your sidebar a two-level rhythm and let you hide deeper sections behind accordion-style folders.

```json
{
  "group": "Authentication",
  "pages": ["auth/overview", "auth/tokens"]
}
```

#### Two rendering tiers

The sidebar shows top-level and nested groups differently:

| Tier | Where it appears | Behavior |
| --- | --- | --- |
| **Top-level group** | Directly under a tab in `docs.json` | Acts as a persistent section header. Always shows its pages. Clicking the header jumps to the first page in the group. |
| **Nested group** | Inside another group's `pages` array | Renders as an accordion-style folder with a chevron toggle. Click to expand or collapse. |

A group's tier is positional: the outermost groups under a tab render as top-level, and any group placed inside another group's `pages` array renders as a nested folder. There is no `topLevel` flag.

Use top-level groups for the major sections of your sidebar (Get Started, Reference, Guides) and nested groups when a top-level section has enough pages that a second level of hierarchy helps the reader scan. See [Nested Groups](#nested-groups) for the JSON shape.

#### How nested groups behave

<Frame caption="A nested group in its collapsed state. The chevron points right and the child pages are hidden.">
  <img src="/images/navigation/sidebar-group-collapsed.webp" alt="Sidebar with the 'Privacy & Access' nested group collapsed: chevron points right, child pages hidden" width="320" height="900" />
</Frame>

- **Auto-expand to the current page.** The group containing the page you are viewing opens automatically, so the active link is always visible.
- **Click to toggle.** Clicking a nested group's header expands it (and navigates to its first page) or collapses it if it is already open.
- **State persists across in-app navigation.** Groups you manually open stay open as you move between pages. A full page refresh resets the open/closed state.

<Frame caption="The same group after navigating to one of its child pages. The chevron rotates and the child pages appear below.">
  <img src="/images/navigation/sidebar-group-expanded.webp" alt="Sidebar with the 'Privacy & Access' nested group expanded: chevron rotated down, three child pages visible below" width="320" height="900" />
</Frame>

#### Group fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `group` | string | Yes | Display label shown in the sidebar. |
| `pages` | array | Yes | List of page paths and/or nested group objects (see [Nested Groups](#nested-groups) for the nested shape). |
| `icon` | string | No | Font Awesome icon name displayed beside the group label. |
| `tag` | string | No | Small badge next to the label (e.g., `"New"`, `"Beta"`). |
| `root` | string | No | Page path the group links to when the label is clicked (instead of jumping to the first child page). |
| `hidden` | boolean | No | Hide the group from the sidebar by default. The pages remain reachable by direct link. |
| `public` | boolean | No | Mark the group as publicly accessible. Defaults to the parent tab's setting. |
| `expanded` | boolean | No | Open the group by default on first page load. Only meaningful for nested groups (top-level groups always show their pages). |

### Pages

Individual documentation pages, referenced by their file path (without `.mdx`):

```json
"pages": ["introduction", "guides/quickstart", "api/endpoints"]
```

By default, the sidebar title is generated from the file name -- dashes become spaces and each word is capitalized. For example, `"api/getting-started"` displays as "Getting Started".

To set a custom sidebar title, use an object instead of a string:

```json
"pages": [
  "guides/quickstart",
  { "page": "deploy/aws", "title": "AWS Route 53 & CloudFront" },
  { "page": "content/seo", "title": "SEO" },
  { "page": "api/users", "title": "List Users", "method": "GET" }
]
```

This is useful for acronyms, proper nouns, and API endpoint badges.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | string | Yes | File path without `.mdx` |
| `title` | string | No | Custom sidebar title |
| `icon` | string | No | Font Awesome icon name |
| `tag` | string | No | Small badge next to the title (e.g., "New", "Beta") |
| `method` | string | No | HTTP method badge: GET, POST, PUT, PATCH, or DELETE |

## Multiple Tabs

Create separate sections for different audiences:

```json
{
  "navigation": {
    "tabs": [
      {
        "tab": "Guides",
        "icon": "book",
        "groups": [
          { "group": "Getting Started", "pages": ["intro", "quickstart"] }
        ]
      },
      {
        "tab": "API Reference",
        "icon": "code",
        "groups": [{ "group": "Endpoints", "pages": ["api/auth", "api/users"] }]
      }
    ]
  }
}
```

## External Tab Links

Link to external documentation or resources directly from tabs:

```json
{
  "navigation": {
    "tabs": [
      { "tab": "Docs", "icon": "book", "groups": [...] },
      { "tab": "GitHub", "icon": "github", "href": "https://github.com/example/repo" }
    ]
  }
}
```

External tabs open in a new browser tab.

## Nested Groups

Organize complex documentation with nested structures:

```json
{
  "group": "SDKs",
  "pages": [
    "sdks/overview",
    {
      "group": "JavaScript",
      "pages": ["sdks/js/install", "sdks/js/usage"]
    },
    {
      "group": "Python",
      "pages": ["sdks/python/install", "sdks/python/usage"]
    }
  ]
}
```

## What's Next?

<Columns cols={2}>
  <Card title="Connect GitHub" icon="github" href="/setup/connecting-github">
    Link your repository for automatic builds
  </Card>
  <Card title="Directory Structure" icon="folder-tree" href="/setup/directory-structure">
    Organize your docs for scale
  </Card>
</Columns>