---
title: Navigation
description: Configure sidebar navigation, tabs, and page ordering.
icon: menu
---

# Navigation

Syntext offers flexible navigation configuration. Define sidebar groups, top-level tabs, and page ordering in your `syntext.json`.

## Sidebar Navigation

The `navigation` array defines your sidebar structure:

```json
{
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["index", "quickstart", "installation"]
    },
    {
      "group": "Guides",
      "pages": [
        "guides/authentication",
        "guides/pagination",
        "guides/error-handling"
      ]
    }
  ]
}
```

### Groups

Groups create collapsible sections in the sidebar:

| Property | Type | Description |
|----------|------|-------------|
| `group` | string | Section heading |
| `pages` | string[] | Array of page paths (without `.mdx`) |

### Page Paths

Page paths are relative to your `docs/` folder:

| Path | File Location |
|------|---------------|
| `"index"` | `docs/index.mdx` |
| `"quickstart"` | `docs/quickstart.mdx` |
| `"guides/auth"` | `docs/guides/auth.mdx` |

## Tab Navigation

For large documentation sites, use tabs to segment content:

```json
{
  "tabs": [
    { "name": "Guides", "url": "/guides", "icon": "book" },
    { "name": "API Reference", "url": "/api-reference", "icon": "api" },
    { "name": "SDKs", "url": "/sdks", "icon": "code" }
  ]
}
```

Each tab can have its own navigation:

```json
{
  "tabs": [
    { "name": "Guides", "url": "/guides", "icon": "book" },
    { "name": "API", "url": "/api-reference", "icon": "api" }
  ],
  "navigation": [
    {
      "group": "Getting Started",
      "tab": "Guides",
      "pages": ["guides/quickstart", "guides/installation"]
    },
    {
      "group": "Endpoints",
      "tab": "API",
      "pages": ["api-reference/users", "api-reference/orders"]
    }
  ]
}
```

### Tab Icons

Available icons: `home`, `book`, `api`, `code`, `terminal`, `settings`, `search`, `users`, `rocket`, `sparkles`.

## Nested Groups

Create sub-sections with nested groups:

```json
{
  "navigation": [
    {
      "group": "API Reference",
      "pages": ["api-reference/overview"]
    },
    {
      "group": "Users",
      "section": "API Reference",
      "pages": [
        "api-reference/users/create",
        "api-reference/users/get",
        "api-reference/users/list"
      ]
    },
    {
      "group": "Orders",
      "section": "API Reference",
      "pages": [
        "api-reference/orders/create",
        "api-reference/orders/get"
      ]
    }
  ]
}
```

The `section` property nests this group under the parent.

## External Links

Link to external resources:

```json
{
  "navigation": [
    {
      "group": "Resources",
      "pages": [
        "changelog",
        { "title": "GitHub", "url": "https://github.com/yourorg" },
        { "title": "Status Page", "url": "https://status.example.com" }
      ]
    }
  ]
}
```

## Anchors

Quick links displayed prominently below the search:

```json
{
  "anchors": [
    { "name": "API Status", "url": "https://status.example.com", "icon": "signal" },
    { "name": "Support", "url": "mailto:support@example.com", "icon": "help" },
    { "name": "Community", "url": "https://discord.gg/yourserver", "icon": "users" }
  ]
}
```

## Auto-Generated Navigation

If you omit the `navigation` field, Syntext generates it from your file structure:

```
docs/
├── index.mdx           → Home (top)
├── getting-started.mdx → Getting Started
└── guides/
    ├── auth.mdx        → Guides / Auth
    └── webhooks.mdx    → Guides / Webhooks
```

Folders become groups, files become pages. Alphabetically sorted.

## Page Ordering

### Via Navigation Array

The order in the `pages` array determines sidebar order:

```json
{
  "pages": ["overview", "quickstart", "advanced"]
}
```

### Via Frontmatter

Override position in frontmatter:

```yaml
---
title: Advanced Guide
sidebarPosition: 10
---
```

Lower numbers appear first.

## Hiding Pages

### Hidden but Accessible

Page is accessible via URL but hidden from navigation:

```yaml
---
title: Secret Page
hidden: true
---
```

### Draft Pages

Page is hidden in production but visible in development:

```yaml
---
title: Work in Progress
draft: true
---
```

## Sidebar Title Override

Display a shorter title in the sidebar:

```yaml
---
title: Complete Guide to Authentication Methods
sidebarTitle: Authentication
---
```

## Example Configuration

```json
{
  "name": "Acme Docs",
  "tabs": [
    { "name": "Guides", "url": "/", "icon": "book" },
    { "name": "API", "url": "/api-reference", "icon": "api" }
  ],
  "anchors": [
    { "name": "GitHub", "url": "https://github.com/acme", "icon": "github" },
    { "name": "Status", "url": "https://status.acme.com", "icon": "signal" }
  ],
  "navigation": [
    {
      "group": "Getting Started",
      "tab": "Guides",
      "pages": ["index", "quickstart", "installation"]
    },
    {
      "group": "Core Concepts",
      "tab": "Guides",
      "pages": ["guides/authentication", "guides/rate-limiting"]
    },
    {
      "group": "API Reference",
      "tab": "API",
      "pages": ["api-reference/overview", "api-reference/authentication"]
    },
    {
      "group": "Users",
      "tab": "API",
      "section": "API Reference",
      "pages": [
        "api-reference/users/create",
        "api-reference/users/get",
        "api-reference/users/update",
        "api-reference/users/delete"
      ]
    }
  ]
}
```