---
title: Organize your navigation
description: Structure tabs and sidebar groups around the tasks your readers need to complete.
url: https://docs.thally.io/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"
  }
}
```

Multiple tabs can each bind their own spec. The first API tab routes at
`/api/default/...`; additional API tabs route at `/api/<tabId>/...`. See
[Multiple API specifications](/guides/api-reference-setup#multiple-api-specifications)
for a complete example.

### 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 pages, groups, and tabs

Pages with `hidden: true` in their frontmatter are automatically removed from
the sidebar, previous/next links, and sitemaps. They remain reachable by direct
URL. If every page in a group is hidden, the group itself is suppressed from the
sidebar.

Set `hidden: true` on a group or tab in `docs.json` to exclude an entire
section while keeping its pages accessible by URL:

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

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

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 --yes @thallylabs/cli@latest check
```

## Next steps

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