- Settings
- Tabs
Settings
Tabs
Add top-level documentation tabs for major sections like guides, API reference, SDKs, or CLI docs.
Tabs create top-level navigation in the header. Use them when a documentation site has major areas that deserve separate sidebars, such as Home, Guides, API Reference, SDKs, or CLI.
Tabs are different from the content-level <Tabs> MDX component. This page covers site navigation tabs in layout.json.
When to use tabs
Use tabs when users need to switch between large content areas.
- Use Home or Guides for product documentation and onboarding.
- Use API Reference for generated OpenAPI pages.
- Use SDKs for language-specific implementation guides.
- Use CLI for command-line workflows if they are large enough to deserve their own lane.
Do not use tabs for small groups of related pages. Use sidebar groups or dropdowns instead.
How tabs work
DocsAlot matches each tab to a route prefix.
For example, a tab with "url": "api-reference" shows sidebar groups whose pages live under /api-reference/*.
The default documentation tab is created from topAnchor. You do not need to add it to the tabs array.
Basic example
{
"topAnchor": {
"name": "Home",
"icon": "house",
"iconType": "solid"
},
"tabs": [
{
"name": "API Reference",
"url": "api-reference",
"icon": "square-terminal",
"iconType": "regular"
}
],
"navigation": [
{
"group": "Getting Started",
"pages": ["quickstart", "installation"]
},
{
"group": "API Reference",
"pages": ["api-reference/index", "api-reference/authentication"]
},
{
"group": "Users",
"pages": [
"api-reference/users/list-users",
"api-reference/users/create-user"
]
}
]
}
With this setup:
- Home shows
quickstartandinstallation. - API Reference shows the groups whose pages start with
api-reference.
Multiple tabs
Add one tab per major content area. Keep prefixes distinct so the active tab is obvious.
{
"topAnchor": {
"name": "Home",
"icon": "house"
},
"tabs": [
{
"name": "Guides",
"url": "guides",
"icon": "book-open",
"iconType": "regular"
},
{
"name": "API",
"url": "api-reference",
"icon": "cloud",
"iconType": "regular"
},
{
"name": "SDKs",
"url": "sdks",
"icon": "code",
"iconType": "solid"
}
],
"navigation": [
{
"group": "Getting Started",
"pages": ["quickstart"]
},
{
"group": "Guides",
"pages": ["guides/install", "guides/configure"]
},
{
"group": "API Reference",
"pages": ["api-reference/index", "api-reference/authentication"]
},
{
"group": "SDKs",
"pages": ["sdks/javascript", "sdks/python"]
}
]
}
Icon options
Each tab supports:
name: the label shown in the headerurl: the route prefix or external URLicon: a Font Awesome icon name, ornoneiconType:regular,solid,duotone,brands,light,thin, orsharp-solidhidden: hides the tab without removing it from the config
DocsAlot also accepts tab instead of name, and href instead of url, for Mintlify-style configs.
Agent-first setup
If you use the DocsAlot CLI with Claude, Codex, or another coding agent, ask for the outcome instead of editing every path manually.
use docsalot cli to add a top-level API Reference tab to this documentation, move all api-reference pages under it, update layout.json, and run a preview locally
After reviewing the preview, publish it:
use docsalot cli to push this documentation to remote and publish
Common mistakes
- Do not include a leading slash in internal tab URLs. Use
"api-reference", not"/api-reference". - Avoid nested prefixes like
"guides"and"guides/sdk"for separate tabs; keep each section’s ownership clear. - Do not add the default Home tab to the
tabsarray. Configure it withtopAnchor. - Make sure the pages for each tab actually use that tab’s route prefix.
