Navigation

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

The navigation array defines your sidebar structure:

{
  "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`

For large documentation sites, use tabs to segment content:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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" }
  ]
}

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

The order in the pages array determines sidebar order:

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

Via Frontmatter

Override position in frontmatter:

---
title: Advanced Guide
sidebarPosition: 10
---

Lower numbers appear first.

Hiding Pages

Hidden but Accessible

Page is accessible via URL but hidden from navigation:

---
title: Secret Page
hidden: true
---

Draft Pages

Page is hidden in production but visible in development:

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

Display a shorter title in the sidebar:

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

Example Configuration

{
  "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"
      ]
    }
  ]
}