---
title: Organize your navigation
description: Structure tabs and sidebar groups around the tasks your readers need to complete.
url: https://pr-6-a9c4e9fe1b6c.thally.app/guides/configuring-navigation
---

# Organize your navigation

Structure tabs and sidebar groups around the tasks your readers need to complete.

Use navigation to reflect reader goals and the order in which they complete
them. Start with a small set of task-based groups; add a tab only when a section
has a distinct audience or purpose.

## The docs.json file

All navigation is controlled by a single file at the project root: `docs.json`. It defines the tabs in the top bar, the sidebar groups within each tab, and the order of pages.

## Structure

```json
{
  "tabs": [
    {
      "tab": "Tab Label",
      "groups": [
        {
          "group": "Section Title",
          "pages": ["page-one", "page-two"]
        }
      ]
    }
  ]
}
```

## Tabs

Each entry in the `tabs` array creates a top-level navigation tab. There are three types:

### Content tab

A tab with sidebar groups and pages:

```json
{
  "tab": "Overview",
  "groups": [
    { "group": "Getting Started", "pages": ["introduction", "quickstart"] },
    { "group": "Core Concepts", "pages": ["authentication"] }
  ]
}
```

### API Reference tab

A tab that auto-generates pages from an OpenAPI spec:

```json
{
  "tab": "API Reference",
  "api": {
    "source": "openapi.yaml",
    "tagsOrder": ["Pets", "Store"],
    "defaultGroup": "General"
  }
}
```

### Link tab

A tab that links to an internal route or external URL:

```json
{
  "tab": "Changelog",
  "href": "/changelog"
}
```

## Groups

Groups create labeled sections in the sidebar. Each group has:

- **`group`** — the section heading displayed in the sidebar
- **`pages`** — an ordered array of page IDs

Page IDs map to file paths under `src/content/`. For example:

| Page ID | File path |
| --- | --- |
| `"introduction"` | `src/content/introduction.mdx` |
| `"guides/getting-started"` | `src/content/guides/getting-started.mdx` |
| `"api/reference"` | `src/content/api/reference.mdx` |

## Adding a new section

To add a new sidebar section, add a group object to the relevant tab:

```json
{
  "tab": "Overview",
  "groups": [
    { "group": "Getting Started", "pages": ["introduction", "quickstart"] },
    { "group": "Advanced", "pages": ["webhooks", "pagination"] },
    { "group": "New Section", "pages": ["my-new-page"] }
  ]
}
```

## Reordering

Pages appear in the sidebar in the exact order listed in the `pages` array. Groups appear in the order they're defined in the `groups` array. Tabs appear left-to-right in the order defined in the `tabs` array.

## Group icons

Add an `icon` field to any group to display an icon next to the group heading in the sidebar:

```json
{
  "group": "Getting Started",
  "icon": "book-open",
  "pages": ["introduction", "quickstart"]
}
```

Available icon names:

| Name | Icon |
| --- | --- |
| `book-open` | Book / documentation |
| `code-simple` | Code brackets |
| `grid-round` | Grid / overview |
| `link-simple` | Link / URL |
| `wrench` | Tools / settings |
| `party-horn` | Features / celebration |
| `telegram` | Send / messaging |
| `envelope` | Email |
| `x-twitter` | X / Twitter |
| `message` | Chat / message |

## Hiding groups and tabs

Set `hidden: true` on a group or tab to exclude it from the sidebar while keeping its pages accessible by URL:

```json
{
  "group": "Internal",
  "hidden": true,
  "pages": ["internal/roadmap", "internal/notes"]
}
```

```json
{
  "tab": "Staff Only",
  "hidden": true,
  "groups": [...]
}
```

Hidden pages remain reachable by direct URL, but they do not appear in
navigation or sitemaps. See [Control search and page visibility](/guides/seo-and-visibility)
for more indexing controls.

## Nested groups

Place a group object inside another group's `pages` array when a section needs
one additional level:

```json
{
  "group": "Deploy",
  "pages": [
    "guides/deploying",
    {
      "group": "Platforms",
      "pages": ["guides/deploy-vercel", "guides/deploy-cloudflare"]
    }
  ]
}
```

Avoid deeper structures. If readers must expand several levels to find a page,
split the material into clearer tabs or reduce the number of categories.

## Verify navigation

Run the local preview and follow every new entry. Confirm the breadcrumb and
previous/next links match the intended progression, then run:

```bash
jq empty docs.json
npx thally check
```

## Next steps

- [docs.json reference](/guides/docs-json-reference)
- [Configure SEO and visibility](/guides/seo-and-visibility)
- [Add redirects](/guides/redirects)