/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog

Navigation

Configure sidebar navigation, tabs, and page ordering.

8 min read

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:

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:

PropertyTypeDescription
groupstringSection heading
pagesstring[]Array of page paths (without .mdx)

The group label names the collapsible sidebar section directly — even when many groups share the same URL prefix (for example platform/accounts/** and platform/transfers/** render as separate Accounts and Transfers groups). Pages not listed in any group fall back to a section derived from their first path segment. On doc engine v1 sites, groups start collapsed by default; the group containing the current page always starts open, and any group a visitor expands or collapses stays that way on future visits (remembered per browser). On doc engine v2, groups start open — the chapters nav folds all but the current one — and appearance.layout.groups "open" removes folding.

Page Paths

Page paths are relative to your docs/ folder:

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

A group's tab places its pages under that header tab regardless of their URL, and wins over the URL-prefix match that tabs otherwise use. Pages in groups without a tab fall back to that URL match. A tab naming a header tab that isn't in tabs is ignored, so pages are never stranded in a section no tab leads to. Nested groups inherit their parent's tab unless they set their own.

A page can also name its own section with section frontmatter, but tab is resolved last and overrides it. See Section and tab placement for the full precedence chain.

Tab Icons

On doc engine v1 the available icons are home, book, api, code, guides, recipes, changelog, sdks, reference, examples, terminal, cli, component, components, layers, rocket, zap, globe. On doc engine v2 any icon name works — see tabs.

Doc engine v2 only — v1 themes ignore icon, nested groups and links, and keep their sidebar exactly as before.

json
{
"navigation": [
{ "group": "Get started", "icon": "rocket", "pages": ["index", "quickstart"] },
{ "group": "API reference", "icon": "braces", "pages": ["api/overview"] },
{ "group": "Users", "section": "API reference", "icon": "users", "pages": ["api/users/create", "api/users/get"] },
{
"group": "Resources",
"pages": [
"changelog",
{ "group": "Community", "pages": ["community/forum"] },
{ "title": "GitHub", "url": "https://github.com/acme" },
{ "title": "Status", "url": "/status" }
]
}
]
}

Group icons

icon draws an icon before the group label, in your preset's heading style. Any v2 icon name works, plus the usual aliases (api draws braces). An unknown name draws no icon. A nested group's icon is drawn before its heading row.

Nested groups

Nest a group inside another in either of two ways:

•
Inline — an object { "group", "icon"?, "pages" } inside a group's pages, where you want it to appear.
•
With section — a top-level group whose section names another top-level group's group label. It moves to the end of that group, after the group's own pages, and inherits the parent's tab unless it sets its own.

A nested group is drawn inside its parent as a bold heading row with its pages indented under it, in the order you list them. Nesting is one level deep: a group nested inside a nested group has its pages placed in the outer nested group. A section that names no group, or that forms a cycle (A in B, B in A), is ignored and the group stays top-level.

The parent's page count includes its nested pages, and they fold with the parent.

A { "title", "url" } entry in pages is a sidebar link, shown where you list it:

•
Absolute URLs (https://… or //…) get a small ↗ arrow and open in a new tab.
•
Site paths (/status) are ordinary links.

A link appears in the same header tab as the page listed just before it in its group — or just after it, if the link comes first. A group that contains only links shows nothing. Links aren't part of prev/next, search or breadcrumbs.

On v1, use topbarLinks or anchors for external links.

Anchors

Doc engine v1 only. Quick links, rendered at the top of the navigation sidebar — the first thing below the header search — and repeated in the mobile navigation drawer:

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:

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

Folder navigation is the default: each page's first folder becomes its group, and files become pages. navigation in syntext.json and sidebarPosition in frontmatter override it (see Page Ordering).

Order on doc engine v2

On a doc engine v2 site the folder order is predictable:

1.
index first
2.
then the pages at the root of docs/
3.
then each folder, A → Z
4.
inside a folder: its own page (guides/index.mdx) first, then its pages, then its subfolders, each A → Z
5.
then pages generated from openapi, in the spec's order

Numbers sort naturally, so 2-setup comes before 10-deploy, and case is ignored:

text
docs/
├── index.mdx → 1
├── quickstart.mdx → 2
├── api/
│ └── auth.mdx → 3
└── guides/
├── index.mdx → 4 (the folder's own page)
├── 2-setup.mdx → 5
├── 10-deploy.mdx → 6
└── advanced/
└── tuning.mdx → 7

navigation still wins: it re-sorts the pages it lists, and only pages it doesn't list keep the folder order. sidebarPosition applies last.

On v1 sites the order is unchanged — pages keep the order they're read from your docs folder, so existing sidebars don't move.

On v2 the preset decides how the sidebar looks. Change it with appearance.layout.nav (tree, pills, mono, chevrons, plain, dock, chapters, overlay or sections) and whether groups fold with appearance.layout.groups (collapsible or open). The sections nav — Orbit's — leads each page with its frontmatter icon.

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. sidebarPosition sorts pages within their own section, and only pages that navigation in syntext.json did not already place — where navigation lists a page, config order wins. Pages without a position keep their existing relative order.

Hiding Pages

Hidden but Accessible

Page is accessible via URL but hidden from navigation:

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

Draft Pages

A draft page is dropped from the sidebar and marked noindex, so it leaves search engines and the site's own index:

yaml
---
title: Work in Progress
draft: true
---
Note
Neither key unpublishes a page

hidden and draft change navigation only. The page is still compiled, still written and still served at its URL, so every existing link and bookmark keeps working. If you need a page gone from the site, remove it from the docs tree — or use audience gating to restrict who can read it.

Display a shorter title in the sidebar:

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

Mark a page as new or in beta with tag — a short badge (at most 20 characters) beside its sidebar entry, on v1 and v2 sites:

yaml
---
title: Webhooks v2
tag: New
---

See Sidebar badge.

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"
]
}
]
}
Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext