Navigation
Configure sidebar navigation, tabs, and page ordering.
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:
Groups
Groups create collapsible sections in the sidebar:
| Property | Type | Description |
|---|---|---|
group | string | Section heading |
pages | string[] | 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:
| 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:
Each tab can have its own navigation:
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.
Group icons, nested groups and links
Doc engine v2 only — v1 themes ignore icon, nested groups and links, and keep
their sidebar exactly as before.
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:
{ "group", "icon"?, "pages" } inside a group's
pages, where you want it to appear.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.
Links
A { "title", "url" } entry in pages is a sidebar link, shown where you list
it:
https://… or //…) get a small ↗ arrow and open in a new tab./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:
Auto-Generated Navigation
If you omit the navigation field, Syntext generates it from your file structure:
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:
index firstdocs/guides/index.mdx) first, then its pages,
then its subfolders, each A → Zopenapi,
in the spec's orderNumbers sort naturally, so 2-setup comes before 10-deploy, and case is
ignored:
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.
Sidebar style on doc engine v2
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:
Via Frontmatter
Override position in frontmatter:
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:
Draft Pages
A draft page is dropped from the sidebar and marked noindex, so it leaves
search engines and the site's own index:
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.
Sidebar Title Override
Display a shorter title in the sidebar:
Sidebar Badge
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:
See Sidebar badge.